# C++ named requirements: CharTraits

> C++ Atlas: `cppatlas.com/w/cpp/named_req/CharTraits` | Source: https://en.cppreference.com/w/cpp/named_req/CharTraits | Domain: Named Requirements | Standards: C++11, C++17, C++20, C++23

CharTraits is a traits class that abstracts basic character and string operations for a given character type.

## Official Specification Summary (cppreference)

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

```cpp
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.

---
Attribution: content from https://en.cppreference.com/w/cpp/named_req/CharTraits (cppreference.com), licensed under CC-BY-SA 3.0 and GFDL. Modified: converted to markdown, study notes added. Offline snapshot of 9 February 2025.