# C++ named requirements: CharTraits

From cppreference.com
< cpp‎ | named req

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)
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_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_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)
istream_iterator | input iterator that reads from std::basic_istream (class template)
ostream_iterator | output iterator that writes to std::basic_ostream (class template)
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)
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 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)

Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/named_req/CharTraits&oldid=110379"