char_traits

template <class charT> struct char_traits;

Character traits

C++ strings can be based on different types of characters. And each type of character can also have different properties, which are known as character traits.

The character traits for a given type define properties of this character type such as how they compare to each other, how they are moved or copied or how they type-cast to/from other types.

Each set of character traits is specified as a template specialization of this class template that has to define the public members listed below, which shall behave as explained, although the internals on how this is achieved can be freely implemented in the class template specialization for the type.

The <string> header defines two specializations for this class template:

• template <> struct char_traits<char>
• template <> struct char_traits<wchar_t>

The public members that these template specializations have are:

typedef charT char_type;

charT is the character container type (the class template parameter). For char_traits<char> this is char, and for char_traits<wchar_t> this is wchar_t.

typedef INT_T int_type;

Where INT_T is a type that can represent all the valid characters representable by a char_type plus an end-of-file value (eof) which is compatible with iostream class member functions. For char_traits<char> this is int, and for char_traits<wchar_t> this is wint_t

typedef OFF_T off_type;

Where OFF_T is an offset type that behaves as streamoff with the iostream class member functions using this type. For both char_traits<char> and char_traits<wchar_t> this is streamoff.

typedef POS_T pos_type;

Where POS_T is a positioning type that behaves as streampos with the iostream class member functions using this type. For both char_traits<char> and char_traits<wchar_t> this is streampos.

typedef STATE_T state_type;

Where STATE_T is a type used to instantiate templates with CopyConstructible requirements. For both char_traits<char> and char_traits<wchar_t> this is mbstate_t.

static void assign ( char_type& c1, char_type& c2);

Assigns the value of c2 to c1. In both, char_traits<char> and char_traits<wchar_t>, this is defined identically to the built-in operator =.

static bool eq ( const char_type& c1, const char_type& c2);

Returns whether character c1 is equal to character c2. In both, char_traits<char> and char_traits<wchar_t>, this is defined identically to the built-in operator ==.

static bool lt ( const char_type& c1, const char_type& c2);

Returns whether character c1 is less than character c2. In both, char_traits<char> and char_traits<wchar_t>, this is defined identically to the built-in operator <.

static int compare ( const char_type* s1, const char_type* s2, size_t n);

Returns 0 if the first n characters of s1 compare equal to those of s2. Returns a negative value if the first character that does not match in that range compares in s1 less than in s2, and a positive value if it does not. Similar in behavior to strncmp C function.

static size_t length ( const char_type* s);

Returns the length of the null-terminated character string s. Similar in behavior to strlen C function.

static const char_type* find ( const char_type* s, size_t n, const char_type& a );

Returns a pointer to the first occurrence of a in the first n characters of character string s. Similar in behavior to strchr C function.

static char_type* move ( char_type* s1, const char_type* s2, size_t n );

Copies n characters from s2 to s1 and returns s1. The original and copied content may overlap in memory. Similar in behavior to memmove C function.

static char_type* copy ( char_type* s1, const char_type* s2, size_t n );

Copies n characters from s2 to s1 and returns s1. The original and copied content shall not overlap in memory. Similar in behavior to memcpy C function.

static char_type* assign ( char_type* s, size_t n, char_type a );

Assigns a to the first n characters of s and returns s. Similar in behavior to memset C function.

static int_type eof ( );

Returns the value used as end-of-file indicator. This value is a value of type int_type such that it does not compare equal to the int_type equivalents of any valid character value. For char_traits<char> this returns EOF, and for char_traits<wchar_t> this returns WEOF

static int_type not_eof ( const int_type& c );

Returns c, except if c is equal to eof(), in which case it return some other value not equal to eof().

static char_type to_char_type ( const int_type& c );

Returns the char_type equivalent to c, if such value exists.

static int_type to_int_type ( const char_type& c );

Returns the int_type equivalent to c.

static bool eq_int_type ( const int_type& c1, const int_type& c2 );

If both the values of c1 and c2 can be obtained by using to_int_type on some character, returns whether they would be equal (as if by member eq). If both c1 and c2 are eof(), also returns true. If only one of them is eof(), returns false.