C++ named requirements: CharTraits

CharTraits is a traits class that abstracts basic character and string operations for a given character type. Most standard library string and input/output classes require a CharTraits template type parameter alongside a corresponding character template type parameter.

Requirements

No operation listed below on CharTraits may throw an exception.

Given

• CharT , a character type
• X , a CharTraits type for type CharT
• c , d , values of type CharT
• p , q , values of type const CharT *
• s , a value of type CharT*
• n , i , j , values of type std::size_t
• e , f , values of type X::int_type
• pos , a value of type X::pos_type
• state , a value of type X::state_type
• r , an lvalue of type CharT

Types

Type	Semantics
X::char_type	CharT
X::int_type	A type that can hold all valid values of X::char_type plus X :: eof ( )
X::off_type	Invokes implementation-defined behavior if not std::streamoff when X is used as the traits template parameter in input/output classes.
X::pos_type	Functions in input/output classes returning this type use X :: pos_type ( X :: off_type ( - 1 ) ) as an invalid value to signal an error Use of this invalid value as an argument to any std::istream , std::ostream or std::streambuf member taking a value of this type is undefined behavior Invokes implementation-defined behavior if this type is not std::streampos when X is used as the traits template parameter in input/output classes
X::state_type	Destructible , CopyAssignable , CopyConstructible , DefaultConstructible

Expressions

Expression	Return type	Semantics	Complexity
X :: eq ( c, d )	bool	Returns: whether c is to be treated as equal to d	Constant
X :: lt ( c, d )	bool	Returns: whether c is to be treated as less than d	Constant
X :: compare ( p, q, n )	int	Returns: ​ 0 ​ if for each i in [ ​ 0 ​ , n ) , X :: eq ( p [ i ] , q [ i ] ) is true Else, a negative value if For some j in [ ​ 0 ​ , n ) , X :: lt ( p [ j ] , q [ j ] ) is true and For each i in [ ​ 0 ​ , j ) , X :: eq ( p [ i ] , q [ i ] ) is true Else a positive value	Linear
X :: length ( p )	std::size_t	Returns: the smallest i such that X :: eq ( p [ i ] , CharT ( ) ) is true	Linear
X :: find ( p, n, c )	const X :: char_type *	Returns: The smallest q in [ p , p + n ) such that X :: eq ( * q, c ) is true ​ 0 ​ otherwise	Linear
X :: move ( s, p, n )	X::char_type*	For each i in [ ​ 0 ​ , n ) , performs X :: assign ( s [ i ] , p [ i ] ) Copies correctly even where the ranges [ p , p + n ) and [ s , s + n ) overlap Returns: s	Linear
X :: copy ( s, p, n )	X::char_type*	Requires: [ p , p + n ) and [ s , s + n ) do not overlap Returns: s For each i in [ ​ 0 ​ , n ) , performs X :: assign ( s [ i ] , p [ i ] )	Linear
X :: assign ( r, d )	(Not used)	Assigns r = d	Constant
X :: assign ( s, n, c )	X::char_type*	For each i in [ ​ 0 ​ , n ) , performs X :: assign ( s [ i ] , c ) . Returns: s	Linear
X :: not_eof ( e )	X::int_type	Returns: e if X :: eq_int_type ( e, X :: eof ( ) ) is false Otherwise a value f such that X :: eq_int_type ( f, X :: eof ( ) ) is false	Constant
X :: to_char_type ( e )	X::char_type	Returns: If for some c , X :: eq_int_type ( e, X :: to_int_type ( c ) ) is true , c Else some unspecified value	Constant
X :: to_int_type ( c )	X::int_type	Returns: some value e , constrained by the definitions of X::to_char_type and X::eq_int_type	Constant
X :: eq_int_type ( e, f )	bool	For all c and d , X :: eq ( c, d ) is equal to X :: eq_int_type ( X :: to_int_type ( c ) , X :: to_int_type ( d ) ) Returns: Yields X :: eq ( c, d ) if for some c and d , e == X :: to_int_type ( c ) and f == X :: to_int_type ( d ) Otherwise, yields true if e and f are both copies of X :: eof ( ) Otherwise, yields false if one of e and f is a copy of X :: eof ( ) and the other is not Otherwise the value is unspecified	Constant
X :: eof ( )	X::int_type	Returns: a value e such that X :: eq_int_type ( e, X :: to_int_type ( c ) ) is false for all values c	Constant

Standard library

CharTraits is required by the following standard library class templates as a template type parameter:

Strings
basic_string	stores and manipulates sequences of characters (class template)
basic_string_view (C++17)	read-only string view (class template)
Streams
basic_ios	manages an arbitrary stream buffer (class template)
basic_istream	wraps a given abstract device ( std::basic_streambuf ) and provides high-level input interface (class template)
basic_ifstream	implements high-level file stream input operations (class template)
basic_istringstream	implements high-level string stream input operations (class template)
basic_ispanstream (C++23)	implements fixed character buffer input operations (class template)
basic_ostream	wraps a given abstract device ( std::basic_streambuf ) and provides high-level output interface (class template)
basic_ofstream	implements high-level file stream output operations (class template)
basic_ostringstream	implements high-level string stream output operations (class template)
basic_osyncstream (C++20)	synchronized output stream wrapper (class template)
basic_ospanstream (C++23)	implements fixed character buffer output operations (class template)
basic_iostream	wraps a given abstract device ( std::basic_streambuf ) and provides high-level input/output interface (class template)
basic_fstream	implements high-level file stream input/output operations (class template)
basic_stringstream	implements high-level string stream input/output operations (class template)
basic_spanstream (C++23)	implements fixed character buffer input/output operations (class template)
Stream iterators
istream_iterator	input iterator that reads from std::basic_istream (class template)
ostream_iterator	output iterator that writes to std::basic_ostream (class template)
Stream buffers
basic_streambuf	abstracts a raw device (class template)
basic_filebuf	implements raw file device (class template)
basic_stringbuf	implements raw string device (class template)
basic_syncbuf (C++20)	synchronized output device wrapper (class template)
basic_spanbuf (C++23)	implements raw fixed character buffer device (class template)
Stream buffer iterators
istreambuf_iterator	input iterator that reads from std::basic_streambuf (class template)
ostreambuf_iterator	output iterator that writes to std::basic_streambuf (class template)

CharTraits is satisfied by the following standard library explicit specializations of 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 > ;		(since C++20) (since C++11) (since C++11)

Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

DR	Applied to	Behavior as published	Correct behavior
LWG 335	C++98	the requirements on the binary overload of assign did not prevent assignments to rvalues	its first argument can only be an lvalue
LWG 352	C++98	X::state_type was only required to be CopyConstructible	it is also required to be CopyAssignable and DefaultConstructible
LWG 3085	C++98	X :: copy ( s, p, n ) only required p not in [ s , s + n ) , which is too weak [1]	requires [ p , p + n ) and [ s , s + n ) not to overlap

1. ↑ [ p , p + n ) and [ s , s + n ) can overlap, using std::memcpy to implement X::copy results in undefined behavior in this case.