[char.traits] (original) (raw)
21.2.1 General [char.traits.general]
Subclause [char.traits] defines requirements on classes representingcharacter traits, and defines a class templatechar_traits<charT>, along with five specializations,char_traits<char>,char_traits<char8_t>,char_traits<char16_t>,char_traits<char32_t>, andchar_traits<wchar_t>, that meet those requirements.
These types and functions are provided as a set of member typedef-names and functions in the template parameter traits used by each such template.
Subclause [char.traits] defines the semantics of these members.
To specialize those templates to generate a string, string view, or iostream class to handle a particular character container type ([defns.character.container])C, that and its related character traits classXare passed as a pair of parameters to the string, string view, or iostream template as parameterscharTandtraits.
IfX::char_typeis not the same type asC, the program is ill-formed.
21.2.2 Character traits requirements [char.traits.require]
In Table 69,Xdenotes a traits class defining types and functions for the character container typeC;candddenote values of typeC;pandqdenote values of typeconst C*;sdenotes a value of typeC*;n,iandjdenote values of typesize_t;eandfdenote values of typeX::int_type;posdenotes a value of typeX::pos_type; andrdenotes an lvalue of typeC.
Operations on X shall not throw exceptions.
Table 69: Character traits requirements [tab:char.traits.req]
| 🔗 | Expression | Return type | Assertion/note | Complexity |
|---|---|---|---|---|
| 🔗 | pre-/post-condition | |||
| 🔗 | X::char_type | C | compile-time | |
| 🔗 | X::int_type | (described in [char.traits.typedefs]) | compile-time | |
| 🔗 | X::off_type | (described in [iostreams.limits.pos] and [iostream.forward]) | compile-time | |
| 🔗 | X::pos_type | (described in [iostreams.limits.pos] and [iostream.forward]) | compile-time | |
| 🔗 | X::state_type | (described in [char.traits.typedefs]) | compile-time | |
| 🔗 | X::eq(c,d) | bool | Returns: whether c is to be treated as equal to d. | constant |
| 🔗 | X::lt(c,d) | bool | Returns: whether c is to be treated as less than d. | constant |
| 🔗 | X::compare(p,q,n) | int | Returns: 0 if for each i in [0, n), X::eq(p[i],q[i])is true; else, a negative value if, for some j in [0, n),X::lt(p[j],q[j]) is true and for each i in [0, j)X::eq(p[i],q[i]) is true; else a positive value. | linear |
| 🔗 | X::length(p) | size_t | Returns: the smallest i such that X::eq(p[i],charT()) is true. | linear |
| 🔗 | X::find(p,n,c) | const X::char_type* | Returns: the smallest q in [p, p+n) such thatX::eq(*q,c) is true, zero otherwise. | linear |
| 🔗 | X::move(s,p,n) | X::char_type* | for each i in [0, n), performs X::assign(s[i],p[i]). Copies correctly even where the ranges [p, p+n) and [s, s+n) overlap. Returns: s. | linear |
| 🔗 | X::copy(s,p,n) | X::char_type* | Preconditions: p not in [s, s+n). Returns: s. for each i in [0, n), performs X::assign(s[i],p[i]). | linear |
| 🔗 | X::assign(r,d) | (not used) | assigns r=d. | constant |
| 🔗 | X::assign(s,n,c) | X::char_type* | for each i in [0, n), performsX::assign(s[i],c). Returns: s. | linear |
| 🔗 | X::not_eof(e) | int_type | Returns: e if X::eq_int_type(e,X::eof()) is false, otherwise a value f such thatX::eq_int_type(f,X::eof()) is false. | constant |
| 🔗 | X::to_char_type(e) | X::char_type | Returns: if for some c, X::eq_int_type(e,X::to_int_type(c))is true, c; else some unspecified value. | constant |
| 🔗 | X::to_int_type(c) | X::int_type | Returns: some value e, constrained by the definitions ofto_char_type and eq_int_type. | constant |
| 🔗 | X::eq_int_type(e,f) | bool | Returns: for all c and d, X::eq(c,d) is equal toX::eq_int_type(X::to_int_type(c), X::to_int_type(d)); otherwise, yields trueif e and f are both copies of X::eof(); otherwise, yields false if one of e and f is a copy of X::eof() and the other is not; otherwise the value is unspecified. | constant |
| 🔗 | X::eof() | X::int_type | Returns: a value e such that X::eq_int_type(e,X::to_int_type(c))is false for all values c. | constant |
The class templatetemplate<class charT> struct char_traits;is provided in the header as a basis for explicit specializations.
21.2.3 Traits typedefs [char.traits.typedefs]
using int_type = _see below_;
Preconditions: int_typeshall be able to represent all of the valid characters converted from the correspondingchar_typevalues, as well as an end-of-file value,eof().227
using state_type = _see below_;
Preconditions: state_type meets the_Cpp17Destructible_ (Table 32),Cpp17CopyAssignable (Table 31),Cpp17CopyConstructible (Table 29), and_Cpp17DefaultConstructible_ (Table 27) requirements.
21.2.4 char_traits specializations [char.traits.specializations]
21.2.4.1 General [char.traits.specializations.general]
namespace std { template<> struct char_traits<char>;template<> struct char_traits<char8_t>;template<> struct char_traits<char16_t>;template<> struct char_traits<char32_t>;template<> struct char_traits<wchar_t>;}
The header defines five specializations of the class templatechar_traits:char_traits<char>,char_traits<char8_t>,char_traits<char16_t>,char_traits<char32_t>, andchar_traits<wchar_t>.
21.2.4.2 struct char_traits [char.traits.specializations.char]
namespace std { template<> struct char_traits<char> { using char_type = char;using int_type = int;using off_type = streamoff;using pos_type = streampos;using state_type = mbstate_t;using comparison_category = strong_ordering;static constexpr void assign(char_type& c1, const char_type& c2) noexcept;static constexpr bool eq(char_type c1, char_type c2) noexcept;static constexpr bool lt(char_type c1, char_type c2) noexcept;static constexpr int compare(const char_type* s1, const char_type* s2, size_t n);static constexpr size_t length(const char_type* s);static constexpr const char_type* find(const char_type* s, size_t n,const char_type& a);static constexpr char_type* move(char_type* s1, const char_type* s2, size_t n);static constexpr char_type* copy(char_type* s1, const char_type* s2, size_t n);static constexpr char_type* assign(char_type* s, size_t n, char_type a);static constexpr int_type not_eof(int_type c) noexcept;static constexpr char_type to_char_type(int_type c) noexcept;static constexpr int_type to_int_type(char_type c) noexcept;static constexpr bool eq_int_type(int_type c1, int_type c2) noexcept;static constexpr int_type eof() noexcept;};}
The type mbstate_t is defined in and can represent any of the conversion states that can occur in animplementation-defined set of supported multibyte character encoding rules.
The two-argument member assign is defined identically to the built-in operator =.
The two-argument members eqand lt are defined identically to the built-in operators== and < for type unsigned char.
The membereof()returnsEOF.
21.2.4.3 struct char_traits<char8_t> [char.traits.specializations.char8.t]
namespace std { template<> struct char_traits<char8_t> { using char_type = char8_t;using int_type = unsigned int;using off_type = streamoff;using pos_type = u8streampos;using state_type = mbstate_t;using comparison_category = strong_ordering;static constexpr void assign(char_type& c1, const char_type& c2) noexcept;static constexpr bool eq(char_type c1, char_type c2) noexcept;static constexpr bool lt(char_type c1, char_type c2) noexcept;static constexpr int compare(const char_type* s1, const char_type* s2, size_t n);static constexpr size_t length(const char_type* s);static constexpr const char_type* find(const char_type* s, size_t n,const char_type& a);static constexpr char_type* move(char_type* s1, const char_type* s2, size_t n);static constexpr char_type* copy(char_type* s1, const char_type* s2, size_t n);static constexpr char_type* assign(char_type* s, size_t n, char_type a);static constexpr int_type not_eof(int_type c) noexcept;static constexpr char_type to_char_type(int_type c) noexcept;static constexpr int_type to_int_type(char_type c) noexcept;static constexpr bool eq_int_type(int_type c1, int_type c2) noexcept;static constexpr int_type eof() noexcept;};}
The two-argument members assign, eq, and ltare defined identically to the built-in operators =, ==, and < respectively.
The member eof() returns an implementation-defined constant that cannot appear as a valid UTF-8 code unit.
21.2.4.4 struct char_traits<char16_t> [char.traits.specializations.char16.t]
namespace std { template<> struct char_traits<char16_t> { using char_type = char16_t;using int_type = uint_least16_t;using off_type = streamoff;using pos_type = u16streampos;using state_type = mbstate_t;using comparison_category = strong_ordering;static constexpr void assign(char_type& c1, const char_type& c2) noexcept;static constexpr bool eq(char_type c1, char_type c2) noexcept;static constexpr bool lt(char_type c1, char_type c2) noexcept;static constexpr int compare(const char_type* s1, const char_type* s2, size_t n);static constexpr size_t length(const char_type* s);static constexpr const char_type* find(const char_type* s, size_t n,const char_type& a);static constexpr char_type* move(char_type* s1, const char_type* s2, size_t n);static constexpr char_type* copy(char_type* s1, const char_type* s2, size_t n);static constexpr char_type* assign(char_type* s, size_t n, char_type a);static constexpr int_type not_eof(int_type c) noexcept;static constexpr char_type to_char_type(int_type c) noexcept;static constexpr int_type to_int_type(char_type c) noexcept;static constexpr bool eq_int_type(int_type c1, int_type c2) noexcept;static constexpr int_type eof() noexcept;};}
The two-argument members assign,eq, and lt are defined identically to the built-in operators =, ==, and<, respectively.
The member eof() returns animplementation-defined constant that cannot appear as a valid UTF-16 code unit.
21.2.4.5 struct char_traits<char32_t> [char.traits.specializations.char32.t]
namespace std { template<> struct char_traits<char32_t> { using char_type = char32_t;using int_type = uint_least32_t;using off_type = streamoff;using pos_type = u32streampos;using state_type = mbstate_t;using comparison_category = strong_ordering;static constexpr void assign(char_type& c1, const char_type& c2) noexcept;static constexpr bool eq(char_type c1, char_type c2) noexcept;static constexpr bool lt(char_type c1, char_type c2) noexcept;static constexpr int compare(const char_type* s1, const char_type* s2, size_t n);static constexpr size_t length(const char_type* s);static constexpr const char_type* find(const char_type* s, size_t n,const char_type& a);static constexpr char_type* move(char_type* s1, const char_type* s2, size_t n);static constexpr char_type* copy(char_type* s1, const char_type* s2, size_t n);static constexpr char_type* assign(char_type* s, size_t n, char_type a);static constexpr int_type not_eof(int_type c) noexcept;static constexpr char_type to_char_type(int_type c) noexcept;static constexpr int_type to_int_type(char_type c) noexcept;static constexpr bool eq_int_type(int_type c1, int_type c2) noexcept;static constexpr int_type eof() noexcept;};}
The two-argument members assign,eq, and lt are defined identically to the built-in operators =, ==, and<, respectively.
The member eof() returns animplementation-defined constant that cannot appear as a Unicode code point.
21.2.4.6 struct char_traits<wchar_t> [char.traits.specializations.wchar.t]
namespace std { template<> struct char_traits<wchar_t> { using char_type = wchar_t;using int_type = wint_t;using off_type = streamoff;using pos_type = wstreampos;using state_type = mbstate_t;using comparison_category = strong_ordering;static constexpr void assign(char_type& c1, const char_type& c2) noexcept;static constexpr bool eq(char_type c1, char_type c2) noexcept;static constexpr bool lt(char_type c1, char_type c2) noexcept;static constexpr int compare(const char_type* s1, const char_type* s2, size_t n);static constexpr size_t length(const char_type* s);static constexpr const char_type* find(const char_type* s, size_t n,const char_type& a);static constexpr char_type* move(char_type* s1, const char_type* s2, size_t n);static constexpr char_type* copy(char_type* s1, const char_type* s2, size_t n);static constexpr char_type* assign(char_type* s, size_t n, char_type a);static constexpr int_type not_eof(int_type c) noexcept;static constexpr char_type to_char_type(int_type c) noexcept;static constexpr int_type to_int_type(char_type c) noexcept;static constexpr bool eq_int_type(int_type c1, int_type c2) noexcept;static constexpr int_type eof() noexcept;};}
The two-argument membersassign,eq, andltare defined identically to the built-in operators=,==, and<, respectively.
The membereof()returnsWEOF.