Apache C++ Standard Library Reference Guide

## char_traits

Library: Strings

    Does not inherit

- Local Index
- Summary
- Synopsis
- Specializations
- Description
- Interface
- Member Types
- Types: Default Values
- Value Functions
- Test Functions
- Conversion Functions
- See Also
- Standards Conformance

### Local Index

#### Members

assign() char_type compare() copy() eof() | eq() eq_int_type() find() int_type length() | lt() move() not_eof() off_type pos_type | state_type to_char_type() to_int_type()

### Summary

A traits class with types and operations for the basic_string container and iostream classes

### Synopsis

    #include <string>

    namespace std {
      template<class charT>
      struct char_traits;
    }

### Specializations

    namespace std {
      template<> struct char_traits<char>;
      template<> struct char_traits<wchar_t>;
    }

### Description

The structure template char_traits defines the types and functions necessary to implement the iostreams and string class templates. It is templatized on `charT`, which represents the character container type. Each specialized version of char_traits includes the default definitions corresponding to the specialized character container type.

Users have to provide specialization for char_traits if they use character types other than `char` and `wchar_t`.

### Interface

    namespace std {

      template<class charT>
      struct char_traits {

        typedef charT       char_type;
        typedef INT_T       int_type;
        typedef POS_T       pos_type;
        typedef OFF_T       off_type;
        typedef STATE_T     state_type;

        static char_type    to_char_type(const int_type&);
        static int_type     to_int_type(const char_type&);
        static bool         eq(const char_type&,const char_type&);
        static bool         eq_int_type(const int_type&,
                                        const int_type&);

        static int_type         eof();
        static int_type         not_eof(const int_type&);

        static void             assign(char_type&,
                                       const char_type&);
        static bool             lt(const char_type&,
                                   const char_type&);
        static int              compare(const char_type*,
                                        const char_type*,size_t);
        static size_t           length(const char_type*);
        static const char_type* find(const char_type*,int n,
                                     const char_type&);

        static char_type*       move(char_type*,
                                     const char_type*,size_t);
        static char_type*       copy(char_type*,const char_type*,
                                     size_t);
        static char_type*       assign(char_type*,size_t,
                                       char_type);
      };
    }

### Member Types

    char_type

The type `char_type` represents the character container type. It must be convertible to `int_type`.

    int_type

The type `int_type` is another character container type that can also hold an end-of-file value. It is used as the return type of some of the iostream class member functions. If `char_type` is either `char` or `wchar_t`, `int_type` is `int` or `wint_t`, respectively.

    off_type

The type `off_type` represents offsets to positional information. It is used to represent:

- A signed displacement, measured in characters, from a specified position within a sequence.

- An absolute position within a sequence.

The value `off_type(-1)` can be used as an error indicator. Value of type `off_type` can be converted to type `pos_type`, but no validity of the resulting `pos_type` value is ensured.

If `char_type` is either `char` or `wchar_t`, `off_type` is `streamoff`.

    pos_type

The type `pos_type` describes an object that can store all the information necessary to restore an arbitrary sequence to a previous stream position and conversion state. The conversion `pos_type(off_type(-1))` constructs the invalid `pos_type` value to signal error.

If `char_type` is either `char` or `wchar_t`, `pos_type` is `streampos` or `wstreampos`, respectively.

    state_type

The type `state_type` holds the conversion state, and is compatible with the function `locale::codecvt()`.

If `char_type` is either `char` or `wchar_t`, `state_type` is `mbstate_t`.

### Types: Default Values

Table 12 lists the default specialization types and their values on `char` and `wchar_t`.

#### Table 12: Default values for types

specialization type | on char | on wchar_t
`char_type` | `char` | `wchar_t`
`int_type` | `int` | `wint_t`
`off_type` | `streamoff` | `streamoff`
`pos_type` | `streampos` | `wstreampos`
`state_type` | `mbstate_t` | `mbstate_t`

### Value Functions

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

Assigns one character value to another. The value of `c2` is assigned to `c1`.

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

Assigns one character value to `n` elements of a character array. The value of `a` is assigned to `n` elements of `s`.

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

Copies `n` characters from the object pointed to by `s1` into the object pointed to by `s2`. The ranges of `(s1,s1+n)` and `(s2,s2+n)` may not overlap.

    int_type
    eof();

Returns an `int_type` value that represents the end-of-file. It is returned by several functions to indicate end-of-file state, or to indicate an invalid return value.

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

Looks for the value of `a` in `s`. Only `n` elements of `s` are examined. Returns a pointer to the matched element if one is found. Otherwise returns `0`.

    size_t
    length(const char_type* s);

Returns the length of a null terminated character string pointed to by `s`.

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

Moves `n` characters from the object pointed to by `s1` into the object pointed to by `s2`. The ranges of `(s1,s1+n)` and `(s2,s2+n)` may overlap.

    int_type
    not_eof(const int_type& c);

Returns `c` if `c` is not equal to the end-of-file value. Otherwise returns `0`.

### Test Functions

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

Compares `n` values from `s1` with `n` values from `s2`. Returns `1` if `s1` is greater than `s2`, `-1` if `s1` is less than`s2,` or `0` if they are equal.

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

Returns `true` if `c1` and `c2` represent the same character.

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

Returns `true` if `c1` and `c2` are equal.

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

Returns `true` if `c1` is less than `c2`.

### Conversion Functions

    char_type
    to_char_type(const int_type& c);

Converts a valid character represented by a value of type `int_type` to the corresponding `char_type` value.

    int_type
    to_int_type(const char_type& c);

Converts a valid character represented by a value of type `char_type` to the corresponding `int_type` value.

### See Also

iosfwd, fpos

### Standards Conformance

ISO/IEC 14882:1998 -- International Standard for Information Systems --Programming Language C++, Section 21.1