.\" ident @(#)char_traits.3 .\" Standard Template Library .\" $$RW_INSERT_HEADER "slyrs.man" .TH char_traits 3C++ "02 Apr 1998" "Rogue Wave Software" "-" .ce2 Standard C++ Library Copyright 1998, Rogue Wave Software, Inc. .SH NAME \f2char_traits\fP \ - A traits class with types and operations for the basic_string container and iostream classes. .SH SYNOPSIS .br #include .br template .br struct char_traits .SH DESCRIPTION The template structure_char_traits_defines the types and functions necessary to implement the iostreams and string_template classes. It is templatized on \f2charT\fP, 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 \f2char\fP and \f2wchar_t\fP. .SH INTERFACE .br template .br struct char_traits { .br .RE .RS 1 typedef charT char_type; .br typedef INT_T int_type; .br typedef POS_T pos_type; .br typedef OFF_T off_type; .br typedef STATE_T state_type; .RE .RS 0 .RE .RS 1 static char_type to_char_type(const int_type&); .br static int_type to_int_type(const char_type&); .br static bool eq(const char_type&,const char_type&); .br static bool eq_int_type(const int_type&, .RE .RS 33 const int_type&); .RE .RS 0 .RE .RS 1 static int_type eof(); .br static int_type not_eof(const int_type&); .RE .RS 0 .RE .RS 1 static void assign(char_type&, .RE .RS 32 const char_type&); .RE .RS 1 static bool lt(const char_type&, .RE .RS 28 const char_type&); .RE .RS 1 static int compare(const char_type*, .RE .RS 33 const char_type*,size_t); .RE .RS 1 static size_t length(const char_type*); .br static const char_type* find(const char_type*,int n, .RE .RS 30 const char_type&); .RE .RS 0 .RE .RS 1 static char_type* move(char_type*, .RE .RS 30 const char_type*,size_t); .RE .RS 1 static char_type* copy(char_type*,const char_type*, .RE .RS 30 size_t); .RE .RS 1 static char_type* assign(char_type*,size_t, .RE .RS 32 const char_type&); .RE .RS 0 .br }; .SH TYPES .br char_type .RE .RS 3 The type \f2char_type\fP represents the character container type. It must be convertible to \f2int_type\fP. .RE .br int_type .RE .RS 3 The type \f2int_type\fP 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 \f2char_type\fP is either \f2char\fP or \f2wchar_t\fP, \f2int_type\fP is \f2int\fP or \f2wint_t\fP, respectively. .RE .br off_type .RE .RS 3 The type \f2off_type\fP represents offsets to positional information. It is used to represent: .RS .5i .HP .5i - A signed displacement, measured in characters, from a specified position within a sequence. .HP .5i - An absolute position within a sequence. .RE The value \f2off_type(-1)\fP can be used as an error indicator. Value of type \f2off_type\fP can be converted to type \f2pos_type, \fPbut no validity of the resulting \f2pos_type\fP value is ensured. If \f2char_type\fP is either \f2char\fP or \f2wchar_t\fP, \f2off_type\fP is \f2streamoff\fP or \f2wstreamoff\fP, respectively. .RE .br pos_type .RE .RS 3 The type \f2pos_type\fP 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 \f2pos_type(off_type(-1))\fP constructs the invalid \f2pos_type\fP value to signal error. If \f2char_type\fP is either \f2char\fP or \f2wchar_t\fP, \f2pos_type\fP is \f2streampos\fP or \f2wstreampos\fP, respectively. .RE .br state_type .RE .RS 3 The type \f2state_type\fP holds the conversion state, and is compatible with the function \f2locale::codecvt()\fP. If \f2char_type\fP is either \f2char\fP or \f2wchar_t\fP, \f2state_type\fP is \f2mbstate_t\fP. .RE .SH TYPES DEFAULT-VALUES SPECIALIZATION TYPE ON CHAR ON WCHAR_T \f2char_type\fP \f2char\fP \f2wchar_t\fP \f2int_type\fP \f2int\fP \f2wint_t\fP \f2off_type\fP \f2streamoff\fP \f2wstreamoff\fP \f2pos_type\fP \f2streampos\fP \f2wstreampos\fP \f2state_type\fP \f2mbstate_t\fP \f2mbstate_t\fP .SH VALUE FUNCTIONS .br void .br assign(char_type& c1, const char_type& c2); .RE .RS 3 Assigns one character value to another. The value of \f2c2\fP is assigned to \f2c1\fP. .RE .br char_type* .br assign(char_type* s, size_t n, const char_type& a); .RE .RS 3 Assigns one character value to \f2n\fP elements of a character array. The value of \f2a\fP is assigned to \f2n\fP elements of \f2s\fP. .RE .br char_type* .br copy(char_type* s1, const char_type* s2, size_t n); .RE .RS 3 Copies \f2n\fP characters from the object pointed to by \f2s1\fP into the object pointed to by \f2s2\fP. The ranges of \f2(s1,s1+n)\fP and \f2(s2,s2+n)\fP may not overlap. .RE .br int_type .br eof(); .RE .RS 3 Returns an \f2int_type\fP 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. .RE .br const char_type* .br find(const char_type* s, int n, const char_type& a); .RE .RS 3 Looks for the value of \f2a\fP in \f2s\fP. Only \f2n\fP elements of \f2s\fP are examined. Returns a pointer to the matched element if one is found. Otherwise returns \f20\fP. .RE .br size_t .br length(const char_type* s); .RE .RS 3 Returns the length of a null terminated character string pointed to by \f2s\fP. .RE .br char_type* .br move(char_type* s1, const char_type* s2, size_t n); .RE .RS 3 Moves \f2n\fP characters from the object pointed to by \f2s1\fP into the object pointed to by \f2s2\fP. The ranges of \f2(s1,s1+n)\fP and \f2(s2,s2+n)\fP may overlap. .RE .br int_type .br not_eof(const int_type& c); .RE .RS 3 Returns \f2c\fP if \f2c\fP is not equal to the end-of-file value. Otherwise returns \f20\fP. .RE .SH TEST FUNCTIONS .br int .br compare(const char_type* s1,const char_type* s2,size_t n); .RE .RS 3 Compares \f2n\fP values from \f2s1\fP with \f2n\fP values from \f2s2\fP. Returns \f21\fP if \f2s1\fP is greater than \f2s2\fP, \f2-1\fP if \f2s1\fP is less than\f2 s2,\fP or \f20\fP if they are equal. .RE .br bool .br eq(const char_type& c1, const char_type& c2); .RE .RS 3 Returns \f2true\fP if \f2c1\fP and \f2c2\fP represent the same character. .RE .br bool .br eq_int_type(const int_type& c1, const int_type& c2); .RE .RS 3 Returns \f2true\fP if \f2c1\fP and \f2c2\fP are equal. .RE .br bool .br lt(const char_type& c1,const char_type& c2); .RE .RS 3 Returns \f2true\fP if \f2c1\fP is less than \f2c2\fP. .RE .SH CONVERSION FUNCTIONS .br char_type .br to_char_type(const int_type& c); .RE .RS 3 Converts a valid character represented by a value of type \f2int_type\fP to the corresponding \f2char_type\fP value. .RE .br int_type .br to_int_type(const char_type& c); .RE .RS 3 Converts a valid character represented by a value of type \f2char_type\fP to the corresponding \f2int_type\fP value. .RE .SH 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. .SH STANDARDS CONFORMANCE ANSI X3J16/ISO WG21 Joint C++ Committee