# std::char_traits

From cppreference.com
< cpp‎ | string

Defined in header `<string>` |  |
template< class CharT > class char_traits; |  |

The `char_traits` class is a traits class template that abstracts basic character and string operations for a given character type. The defined operation set is such that generic algorithms almost always can be implemented in terms of it. It is thus possible to use such algorithms with almost any possible character or string type, just by supplying a customized `char_traits` class.

The `char_traits` class template serves as a basis for explicit instantiations. The user can provide a specialization for any custom character types. Several specializations are defined for the standard character types.

If an operation on traits emits an exception, the behavior is undefined.

### Standard specializations

Member typedefs of standard specializations are as follows:

Specialization | `char_type` | `int_type` | `pos_type`
--- | --- | --- | ---
std::char_traits<char> | char | int | std::streampos
std::char_traits<wchar_t> | wchar_t | `std::wint_t` | std::wstreampos
std::char_traits<char16_t> (C++11) | char16_t | std::uint_least16_t | std::u16streampos
std::char_traits<char32_t> (C++11) | char32_t | std::uint_least32_t | std::u32streampos
std::char_traits<char8_t> (C++20) | char8_t | unsigned int | std::u8streampos

Member type | Definition (same among all standard specializations)
--- | ---
`off_type` | std::streamoff
`state_type` | std::mbstate_t
`comparison_category` (C++20) | std::strong_ordering

The semantics of the member functions of standard specializations are defined are as follows:

Specialization | `assign` | `eq` | `lt` | `eof`
--- | --- | --- | --- | ---
std::char_traits<char> | = | == for unsigned char | < for unsigned char | EOF
std::char_traits<wchar_t> | = | == | < | `WEOF`
std::char_traits<char16_t> (C++11) | = | == | < | invalid UTF-16 code unit
std::char_traits<char32_t> (C++11) | = | == | < | invalid UTF-32 code unit
std::char_traits<char8_t> (C++20) | = | == | < | invalid UTF-8 code unit

Standard specializations of `char_traits` class template satisfy the requirements of CharTraits.

### Member types

Type | Definition
`char_type` | `CharT`
`int_type` | an integer type that can hold all values of `char_type` plus EOF
`off_type` | implementation-defined
`pos_type` | implementation-defined
`state_type` | implementation-defined

### Member functions

assign [static] | assigns a character (public static member function)
eq lt [static] | compares two characters (public static member function)
move [static] | moves one character sequence onto another (public static member function)
copy [static] | copies a character sequence (public static member function)
compare [static] | lexicographically compares two character sequences (public static member function)
length [static] | returns the length of a character sequence (public static member function)
find [static] | finds a character in a character sequence (public static member function)
to_char_type [static] | converts `int_type` to equivalent `char_type` (public static member function)
to_int_type [static] | converts `char_type` to equivalent `int_type` (public static member function)
eq_int_type [static] | compares two `int_type` values (public static member function)
eof [static] | returns an eof value (public static member function)
not_eof [static] | checks whether a character is eof value (public static member function)

### Example

User-defined character traits may be used to provide case-insensitive comparison:

Run this code

    #include <string>
    #include <string_view>
    #include <iostream>
    #include <cctype>

    struct ci_char_traits : public std::char_traits<char>
    {
        static char to_upper(char ch)
        {
            return std::toupper((unsigned char) ch);
        }

        static bool eq(char c1, char c2)
        {
            return to_upper(c1) == to_upper(c2);
        }

        static bool lt(char c1, char c2)
        {
             return to_upper(c1) < to_upper(c2);
        }

        static int compare(const char* s1, const char* s2, std::size_t n)
        {
            while (n-- != 0)
            {
                if (to_upper(*s1) < to_upper(*s2))
                    return -1;
                if (to_upper(*s1) > to_upper(*s2))
                    return 1;
                ++s1;
                ++s2;
            }
            return 0;
        }

        static const char* find(const char* s, std::size_t n, char a)
        {
            auto const ua (to_upper(a));
            while (n-- != 0)
            {
                if (to_upper(*s) == ua)
                    return s;
                s++;
            }
            return nullptr;
        }
    };

    template<class DstTraits, class CharT, class SrcTraits>
    constexpr std::basic_string_view<CharT, DstTraits>
        traits_cast(const std::basic_string_view<CharT, SrcTraits> src) noexcept
    {
        return {src.data(), src.size()};
    }

    int main()
    {
        using namespace std::literals;

        constexpr auto s1 = "Hello"sv;
        constexpr auto s2 = "heLLo"sv;

        if (traits_cast<ci_char_traits>(s1) == traits_cast<ci_char_traits>(s2))
            std::cout << s1 << " and " << s2 << " are equal\n";
    }

Output:

    Hello and heLLo are equal

### 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 467 | C++98 | for std::char_traits<char>, the semantics of `eq()` and `lt()` are the same as the built-in == and < on char respectively[1] | changed to built-in == and < on unsigned char

1. ↑ Most implementations call std::memcmp() for efficiency, which interprets the data as arrays of unsigned char. If char is signed on such implementations, std::char_traits<char> fails to satisfy the requirements of CharTraits.

### See also

basic_string | stores and manipulates sequences of characters (class template)

Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/string/char_traits&oldid=152898"