На этом шаге мы закончим изучение этого вопроса.
Фацет codecvt, как и ctype, является производным от базового класса с определением перечисляемого типа. Базовый класс называется codecvt_base, в нем определяется перечисляемый тип result. Значения перечисляемого типа требуются при описании результатов вызова функций codecvt. Точный смысл каждого значения зависит от вызываемой функции. В таблице 1 перечислены функции фацета codecvt.
| Выражение | Описание |
|---|---|
| cvt.in(s, fb, fe, fn, tb, te, tn) | Преобразует внешнее представление к внутреннему |
| cvt.out(s, fb, fe, fn, tb, te, tn) | Преобразует внутреннее представление к внешнему |
| cvt.unshift(s, tb, te, tn) | Записывает служебную последовательность для переключения к исходному состоянию сдвига |
| cvt.encoding() | Возвращает информацию о внешней кодировке |
| cvt.always_noconv() | Возвращает true, если преобразование не выполняется |
| cvt.length(s, fb, fe, max) | Возвращает количество объектов externT в интервале между fb и fe для получения max символов во внутреннем представлении |
| cvt.max_length() | Возвращает максимальное количество объектов externT, необходимых для создания одного объекта internT |
Функция in() преобразует внешнее представление к внутреннему. Аргумент s содержит ссылку на stateT. Перед преобразованием этот аргумент определяет состояние сдвига, используемое в начале преобразования, а после преобразования в нем сохраняется итоговое состояние сдвига. Переданное состояние сдвига может отличаться от исходного, если текущий буфер не является первым из обрабатываемых буферов. Аргументы fb и fe относятся к типу const internT* и определяют соответственно начало и конец входного буфера. Аргументы tb и te относятся к типу externT* и определяют соответственно начало и конец выходного буфера. Аргументы fn (тип const extern&*&) и tn (тип internT*&) содержат ссылки, в которых возвращается конец преобразуемой последовательности символов во входном и выходном буферах соответственно. Конец любого буфера может быть достигнут до того, как будет достигнут конец другого буфера. Функция возвращает значение типа codecvt_base::result (таблица 2).
| Выражение | Описание |
|---|---|
| ok | Все исходные символы были успешно преобразованы |
| partial | He все символы были успешно преобразованы, или для получения преобразованного символа нужны дополнительные символы |
| error | Обнаружен исходный символ, который невозможно преобразовать |
| noconv | Преобразование не требуется |
Возвращаемое значение ok означает, что функция успешно справилась со своей работой. Если fn==fе, это означает, что входной буфер был обработан полностью, а последовательность в интервале между tb и tn содержит результат преобразования. Символы этой последовательности соответствуют символам входной последовательности (возможно - с добавлением законченного символа от предыдущего преобразования). Если аргумент s функции in() не находился в исходном состоянии, возможно, в нем хранился незавершенный символ от предыдущего преобразования.
Если функция возвращает значение partial, это может означать одно из двух: либо выходной буфер был заполнен до завершения чтения входного буфера, либо входной буфер был прочитан полностью при наличии незавершенных символов (например, если последний байт входной последовательности был частью служебной последовательности для переключения состояний сдвига). Если fe==fn, входной буфер был прочитан полностью. В этом случае последовательность между tb и tn содержит все полностью преобразованные символы. Информация, необходимая для завершения преобразования символа, сохраняется в состоянии сдвига s. Если fe!=fn, входной буфер был прочитан не полностью. В этом случае следующее преобразование будет продолжено с позиции fn.
Возвращаемое значение noconv является признаком особой ситуации: оно означает, что преобразования внешнего представления во внутреннее не потребовалось. В этом случае fn присваивается fb, a tn присваивается tb. В приемной последовательности не сохраняется ничего, поскольку вся необходимая информация уже хранится во входной последовательности.
Если функция возвращает код error, это означает, что исходный символ преобразовать не удалось. Это может произойти по нескольким причинам: например, в приемной кодировке отсутствует представление для соответствующего символа или обработка входной последовательности завершилась в недопустимом состоянии сдвига. Стандарт C++ не определяет механизм, который позволил бы точнее определить причину ошибки.
Функция out() эквивалентна in(), но она работает в обратном направлении, то есть преобразует внутреннее представление во внешнее. Аргументы и возвращаемые значения двух функций совпадают, различаются только типы аргументов: tb и te относятся к типу const internT*, a fb и fe - к типу const externT*. To же можно сказать и об аргументах fn и tn.
Функция unshift() вставляет символы, необходимые для завершения последовательности, когда в аргументе s передается текущее состояние преобразования. Обычно это означает, что состояние сдвига возвращается к исходному. Завершается только внешнее представление. Аргументы tb и tf относятся к типу externT*, а аргумент tn - к типу externT&*. Интервал между tb н te определяет выходной буфер, в котором сохраняются символы. Конец выходной последовательности хранится в tn. Значения, возвращаемые функций unshift(), перечислены в таблице 3.
| Выражение | Описание |
|---|---|
| ok | Последовательность завершена успешно |
| partial | Для завершения последовательности нужны дополнительные символы |
| error | Недействительное состояние |
| noconv | Для завершения последовательности символы не требуются |
Функция encoding() возвращает дополнительную информацию о кодировке внешнего представления. Если encoding() возвращает -1, преобразование зависит от состояния. Если encoding() возвращает 0, то количество объектов externT, необходимых для построения символа во внутренней кодировке, является переменной величиной. В противном случае функция возвращает количество объектов externT, необходимых для построения internT. Эта информация может использоваться для выделения буфера соответствующего размера.
Функция always_noconv() возвращает true, если функции in() и out() никогда не выполняют преобразования. Например, стандартная реализация codecvt<char, char, mbstate_t> преобразований не выполняет, поэтому для этого фацета функция always_noconv() всегда возвращает true. Тем не менее это относится только к фацету codecvt локального контекста "С", другие экземпляры этого фацета могут выполнять преобразования.
Функция length() возвращает количество объектов externT в интервале между fb и fe, необходимых для построения max символов типа internT. Если интервал между fb и fe содержит менее max полных символов типа internT, возвращается количество объектов externT, необходимых для построения максимально возможного количества символов типа internT.
На следующем шаге мы рассмотрим организацию контекстной сортировки.
