Standard C++ Library
Copyright 1998, Rogue Wave Software, Inc.

NAME

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

SYNOPSIS

 
 
#include <string>
template<class charT>
struct char_traits
 
 
 

DESCRIPTION

 
 
The template structure_char_traits<charT>_defines the types and functions necessary to implement the iostreams and string_template classes. It is templatized on charT, which represents the character container type. Each specialized version of char_traits<charT>_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

 
 
 
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,

const char_type&);

 
};
 
 
 

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 or wstreamoff, respectively. 
 

 
 
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

 
 
 
 
SPECIALIZATION TYPEON CHARON WCHAR_T
 
 
char_typecharwchar_t
 
int_typeintwint_t
 
off_typestreamoffwstreamoff
 
pos_typestreamposwstreampos
 
state_typembstate_tmbstate_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, const 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(3C++), fpos(3C++)
 
Working Paper for Draft Proposed International Standard for Information Systems--Programming Language C++, Section 21.1.4, 21.1.5, 27.1.2.
 
 
 

STANDARDS CONFORMANCE

 
 
ANSI X3J16/ISO WG21 Joint C++ Committee
 

Rogue Wave Software  —  Last change: 02 Apr 1998