C++ named requirements: CharTraits

From cppreference.com
< cpp‎ | named req
 
 
C++ named requirements
Basic
Type properties
Library-Wide
Container
Container Elements
Iterator
Stream I/O
Formatting
(C++20)
Random Numbers
Concurrency
(C++11)
(C++11)
Other
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


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

Strings
stores and manipulates sequences of characters
(class template)
read-only string view
(class template)
Streams
manages an arbitrary stream buffer
(class template)
wraps a given abstract device (std::basic_streambuf)
and provides high-level input interface
(class template)
implements high-level file stream input operations
(class template)
implements high-level string stream input operations
(class template)
implements fixed character buffer input operations
(class template)
wraps a given abstract device (std::basic_streambuf)
and provides high-level output interface
(class template)
implements high-level file stream output operations
(class template)
implements high-level string stream output operations
(class template)
synchronized output stream wrapper
(class template)
implements fixed character buffer output operations
(class template)
wraps a given abstract device (std::basic_streambuf)
and provides high-level input/output interface
(class template)
implements high-level file stream input/output operations
(class template)
implements high-level string stream input/output operations
(class template)
implements fixed character buffer input/output operations
(class template)
Stream iterators
input iterator that reads from std::basic_istream
(class template)
output iterator that writes to std::basic_ostream
(class template)
Stream buffers
abstracts a raw device
(class template)
implements raw file device
(class template)
implements raw string device
(class template)
synchronized output device wrapper
(class template)
implements raw fixed character buffer device
(class template)
Stream buffer iterators
input iterator that reads from std::basic_streambuf
(class template)
output iterator that writes to std::basic_streambuf
(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<char8_t>;
template<> class char_traits<char16_t>;

template<> class char_traits<char32_t>;


(since C++20)
(since C++11)
(since C++11)