std::char_traits

C++

Language

Headers

Freestanding and hosted implementations

Named requirements

Language support library

Concepts library (C++20)

Diagnostics library

Utilities library

Strings library

Containers library

Algorithms library

Iterators library

Numerics library

Input/output library

Localizations library

Regular expressions library (C++11)

Atomic operations library (C++11)

Thread support library (C++11)

Filesystem library (C++17)

Technical Specifications

Strings library

Null-terminated strings

Byte strings

Multibyte strings

Wide strings

Classes

basic_string

basic_string_view (C++17)

char_traits

std::char_traits

Member functions

char_traits::assign

char_traits::cmp

char_traits::move

char_traits::copy

char_traits::compare

char_traits::length

char_traits::find

char_traits::to_char_type

char_traits::to_int_type

char_traits::eq_int_type

char_traits::eof

char_traits::not_eof

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.

The values of the member typedefs are as follows.

Specialization	char_type	int_type	off_type	pos_type	state_type
char_traits<char>	char	int	std::streamoff	std::streampos	std::mbstate_t
char_traits<wchar_t>	wchar_t	std::wint_t	std::streamoff	std::wstreampos	std::mbstate_t
char_traits<char16_t> (C++11)	char16_t	std::uint_least16_t	std::streamoff	std::u16streampos	std::mbstate_t
char_traits<char32_t> (C++11)	char32_t	std::uint_least32_t	std::streamoff	std::u32streampos	std::mbstate_t

The semantics of the member functions are defined are as follows.

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

The char_traits class template satisfies 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)
eqlt [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 <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, 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, int n, char a) {
        auto const ua (to_upper(a));
        while ( n-- != 0 ) 
        {
            if (to_upper(*s) == ua)
                return s;
            s++;
        }
        return nullptr;
    }
};

using ci_string = std::basic_string<char, ci_char_traits>;

std::ostream& operator<<(std::ostream& os, const ci_string& str) {
    return os.write(str.data(), str.size());
}

int main()
{
    ci_string s1 = "Hello";
    ci_string s2 = "heLLo";
    if (s1 == s2)
        std::cout << s1 << " and " << s2 << " are equal\n";
}

Output:

Hello and heLLo are equal

See also

basic_string

stores and manipulates sequences of characters (class template)