C++ named requirements: CharTraits

CharTraits — это класс характеристик, который абстрагирует базовые операции с символами и строками для заданного типа символов. Большинство строковых классов и классов ввода/вывода стандартной библиотеки требуют параметр шаблона CharTraits вместе с соответствующим параметром шаблона типа символа.

Содержание 1 Требования 2 Типы 3 Выражения 4 Стандартная библиотека 4.1 Строки 4.2 Потоки 4.3 Итераторы потоков 4.4 Буферы потоков 4.5 Итераторы буферов потоков 5 Отчеты о дефектах

Требования

Ни одна из перечисленных ниже операций над CharTraits не должна вызывать исключений.

Дано

• CharT , тип символа
• X , CharTraits тип для типа CharT
• c , d , значения типа CharT
• p , q , значения типа const CharT *
• s , значение типа CharT*
• n , i , j , значения типа std::size_t
• e , f , значения типа X::int_type
• pos , значение типа X::pos_type
• state , значение типа X::state_type
• r , l-value типа CharT

Типы

Тип	Семантика
X::char_type	CharT
X::int_type	Тип, который может содержать все допустимые значения X::char_type плюс X :: eof ( )
X::off_type	Вызывает поведение, определяемое реализацией, если не std::streamoff когда X используется как параметр шаблона traits в классах ввода/вывода.
X::pos_type	Функции в классах ввода/вывода, возвращающие этот тип, используют X :: pos_type ( X :: off_type ( - 1 ) ) как недопустимое значение для сигнализации об ошибке Использование этого недопустимого значения в качестве аргумента для любого члена std::istream , std::ostream или std::streambuf , принимающего значение этого типа, является неопределенным поведением Вызывает поведение, определяемое реализацией, если этот тип не является std::streampos когда X используется как параметр шаблона traits в классах ввода/вывода
X::state_type	Destructible , CopyAssignable , CopyConstructible , DefaultConstructible

Выражения

Выражение	Тип возвращаемого значения	Семантика	Сложность
X :: eq ( c, d )	bool	Возвращает: следует ли рассматривать c как равный d	Константная
X :: lt ( c, d )	bool	Возвращает: следует ли рассматривать c как меньший, чем d	Константная
X :: compare ( p, q, n )	int	Возвращает: ​ 0 ​ если для каждого i в [ ​ 0 ​ , n ) , X :: eq ( p [ i ] , q [ i ] ) равно true Иначе, отрицательное значение если Для некоторого j в [ ​ 0 ​ , n ) , X :: lt ( p [ j ] , q [ j ] ) равно true и Для каждого i в [ ​ 0 ​ , j ) , X :: eq ( p [ i ] , q [ i ] ) равно true Иначе положительное значение	Линейная
X :: length ( p )	std::size_t	Возвращает: наименьшее i такое, что X :: eq ( p [ i ] , CharT ( ) ) равно true	Линейная
X :: find ( p, n, c )	const X :: char_type *	Возвращает: Наименьший q в [ p , p + n ) такой, что X :: eq ( * q, c ) равен true ​ 0 ​ в противном случае	Линейная
X :: move ( s, p, n )	X::char_type*	Для каждого i в [ ​ 0 ​ , n ) , выполняет X :: assign ( s [ i ] , p [ i ] ) Копирует корректно даже в случаях, когда диапазоны [ p , p + n ) и [ s , s + n ) перекрываются Возвращает: s	Линейная
X :: copy ( s, p, n )	X::char_type*	Требования: [ p , p + n ) и [ s , s + n ) не перекрываются Возвращает: s Для каждого i в [ ​ 0 ​ , n ) , выполняет X :: assign ( s [ i ] , p [ i ] )	Линейная
X :: assign ( r, d )	(Не используется)	Присваивает r = d	Константная
X :: assign ( s, n, c )	X::char_type*	Для каждого i в диапазоне [ ​ 0 ​ , n ) , выполняет X :: assign ( s [ i ] , c ) . Возвращает: s	Линейная
X :: not_eof ( e )	X::int_type	Возвращает: e если X :: eq_int_type ( e, X :: eof ( ) ) равно false Иначе значение f такое, что X :: eq_int_type ( f, X :: eof ( ) ) равно false	Константная
X :: to_char_type ( e )	X::char_type	Возвращает: Если для некоторого c , X :: eq_int_type ( e, X :: to_int_type ( c ) ) равно true , c Иначе некоторое неопределённое значение	Константная
X :: to_int_type ( c )	X::int_type	Возвращает: некоторое значение e , ограниченное определениями X::to_char_type и X::eq_int_type	Константная
X :: eq_int_type ( e, f )	bool	Для всех c и d , X :: eq ( c, d ) равно X :: eq_int_type ( X :: to_int_type ( c ) , X :: to_int_type ( d ) ) Возвращает: Возвращает X :: eq ( c, d ) если для некоторых c и d , e == X :: to_int_type ( c ) и f == X :: to_int_type ( d ) Иначе, возвращает true если e и f оба являются копиями X :: eof ( ) Иначе, возвращает false если один из e и f является копией X :: eof ( ) а другой - нет Иначе значение не определено	Константная
X :: eof ( )	X::int_type	Возвращает: значение e такое, что X :: eq_int_type ( e, X :: to_int_type ( c ) ) равно false для всех значений c	Константа

Стандартная библиотека

CharTraits требуется следующими шаблонами классов стандартной библиотеки в качестве параметра шаблонного типа:

Строки
basic_string	хранит и манипулирует последовательностями символов (шаблон класса)
basic_string_view (C++17)	представление строки только для чтения (шаблон класса)
Потоки
basic_ios	управляет произвольным буфером потока (шаблон класса)
basic_istream	оборачивает заданное абстрактное устройство ( std::basic_streambuf ) и предоставляет высокоуровневый интерфейс ввода (шаблон класса)
basic_ifstream	реализует операции высокоуровневого ввода файлового потока (шаблон класса)
basic_istringstream	реализует операции высокоуровневого ввода строкового потока (шаблон класса)
basic_ispanstream (C++23)	реализует операции ввода из фиксированного буфера символов (шаблон класса)
basic_ostream	оборачивает заданное абстрактное устройство ( std::basic_streambuf ) и предоставляет высокоуровневый интерфейс вывода (шаблон класса)
basic_ofstream	реализует операции высокоуровневого вывода в файловый поток (шаблон класса)
basic_ostringstream	реализует операции высокоуровневого вывода в строковый поток (шаблон класса)
basic_osyncstream (C++20)	обёртка синхронизированного выходного потока (шаблон класса)
basic_ospanstream (C++23)	реализует операции вывода в фиксированный буфер символов (шаблон класса)
basic_iostream	оборачивает заданное абстрактное устройство ( std::basic_streambuf ) и предоставляет высокоуровневый интерфейс ввода/вывода (шаблон класса)
basic_fstream	реализует высокоуровневые операции ввода/вывода файлового потока (шаблон класса)
basic_stringstream	реализует высокоуровневые операции ввода/вывода для строковых потоков (шаблон класса)
basic_spanstream (C++23)	реализует операции ввода/вывода для фиксированного буфера символов (шаблон класса)
Итераторы потоков
istream_iterator	входной итератор, который читает из std::basic_istream (шаблон класса)
ostream_iterator	выходной итератор, который записывает в std::basic_ostream (шаблон класса)
Буферы потоков
basic_streambuf	абстрагирует базовое устройство (шаблон класса)
basic_filebuf	реализует базовое файловое устройство (шаблон класса)
basic_stringbuf	реализует необработанное строковое устройство (шаблон класса)
basic_syncbuf (C++20)	обёртка синхронизированного устройства вывода (шаблон класса)
basic_spanbuf (C++23)	реализует устройство необработанного фиксированного буфера символов (шаблон класса)
Итераторы потоковых буферов
istreambuf_iterator	входной итератор, который читает из std::basic_streambuf (шаблон класса)
ostreambuf_iterator	выходной итератор, записывающий в std::basic_streambuf (шаблон класса)

CharTraits удовлетворяется следующими стандартными библиотечными явными специализациями std::char_traits :

template <> class char_traits < char > ; template <> class char_traits < wchar_t > ; template <> class char_traits < char8_t > ; template <> class char_traits < char16_t > ; template <> class char_traits < char32_t > ;		(начиная с C++20) (начиная с C++11) (начиная с C++11)

Отчёты о дефектах

Следующие отчеты об изменениях поведения, влияющие на дефекты, были применены задним числом к ранее опубликованным стандартам C++.

DR	Applied to	Behavior as published	Correct behavior
LWG 335	C++98	требования к бинарной перегрузке assign не предотвращали присваивания rvalue	её первый аргумент может быть только lvalue
LWG 352	C++98	X::state_type требовался только быть CopyConstructible	также требуется быть CopyAssignable и DefaultConstructible
LWG 3085	C++98	X :: copy ( s, p, n ) требовал только p не в [ s , s + n ) , что слишком слабо [1]	требует [ p , p + n ) и [ s , s + n ) не перекрывались

1. ↑ [ p , p + n ) и [ s , s + n ) могут перекрываться, использование std::memcpy для реализации X::copy в этом случае приводит к неопределенному поведению.