C++ named requirements: CharTraits

 

C++

Language

Standard Library Headers

Freestanding and hosted implementations

Named requirements

Language support library

Concepts library (C++20)

Diagnostics library

Utilities library

Strings library

Containers library

Iterators library

Ranges library (C++20)

Algorithms library

Numerics library

Input/output library

Localizations library

Regular expressions library (C++11)

Atomic operations library (C++11)

Thread support library (C++11)

Filesystem library (C++17)

Technical Specifications

 

C++ named requirements

Basic
DefaultConstructible CopyAssignable CopyConstructible	MoveAssignable (C++11) MoveConstructible (C++11) Destructible
Layout
TrivialType (C++11) TriviallyCopyable (C++11)	StandardLayoutType (C++11) PODType
Library-Wide
EqualityComparable LessThanComparable Swappable (C++11) ValueSwappable (C++11) NullablePointer (C++11) Hash (C++11)	Allocator FunctionObject Callable Predicate BinaryPredicate Compare
Container
Container SequenceContainer ContiguousContainer (C++17) ReversibleContainer	AssociativeContainer AllocatorAwareContainer UnorderedAssociativeContainer (C++11)
Container Elements
DefaultInsertable (C++11) CopyInsertable (C++11) MoveInsertable (C++11)	EmplaceConstructible (C++11) Erasable (C++11)
Iterator
LegacyIterator LegacyOutputIterator LegacyInputIterator LegacyForwardIterator	LegacyBidirectionalIterator LegacyRandomAccessIterator LegacyContiguousIterator (C++17) ConstexprIterator (C++20)
Stream I/O
FormattedInputFunction UnformattedInputFunction	FormattedOutputFunction UnformattedOutputFunction
Random Numbers
SeedSequence (C++11) RandomNumberEngine (C++11)	RandomNumberDistribution (C++11) UniformRandomBitGenerator (C++11) RandomNumberEngineAdaptor (C++11)
Concurrency
BasicLockable (C++11) Lockable (C++11) TimedLockable (C++11)	Mutex (C++11) TimedMutex (C++11) SharedMutex (C++17) SharedTimedMutex (C++14)
Other
CharTraits RegexTraits (C++11) BitmaskType NumericType LiteralType (C++11)	UnaryTypeTrait (C++11) BinaryTypeTrait (C++11) TransformationTrait (C++11) Clock (C++11) TrivialClock (C++11)

 

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 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

expression	return type	semantics	complexity
X::char_type	CharT	Used to refer to the character type	Compile-time
X::int_type		A type that can hold all valid values of X::char_type plus X::eof()	Compile-time
X::off_type		Invokes implementation-defined behaviour if not std::streamoff when X is used as the traits template parameter in input/output classes.	Compile-time
X::pos_type		Functions in input/output classes returning this type use X::pos_type(X::off_type(-1)) is 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 behaviour Invokes implementation-defined behaviour if this type is not std::streampos when X is used as the traits template parameter in input/output classes	Compile-time
X::state_type		Destructible, CopyAssignable, CopyConstructible, DefaultConstructible	Compile-time
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 Zero 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 not in [s,s+n) 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:

basic_string	stores and manipulates sequences of characters (class template)
basic_string_view (C++17)	read-only string view (class template)

CharTraits is satisfied by the following standard library classes:

template<> class char_traits<char>; template<> class char_traits<wchar_t>; template<> class char_traits<char16_t>; template<> class char_traits<char32_t>;		(since C++11) (since C++11)