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

stores and manipulates sequences of characters
(class template)
(C++17)
 read-only string view
(class template)
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)
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)
(C++20)
 synchronized output stream wrapper
(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)
input iterator that reads from std::basic_istream
(class template)
output iterator that writes to std::basic_ostream
(class template)
abstracts a raw device
(class template)
implements raw file device
(class template)
implements raw string device
(class template)
(C++20)
 synchronized output device wrapper
(class template)
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)

© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
http://en.cppreference.com/w/cpp/named_req/CharTraits