Przejdź do głównej zawartości

C++ named requirements:CharTraits

CharTraits is a traits class that abstracts basic character and string operations for a given character type. Most standard library string and input/output classes require a CharTraits template type parameter alongside a corresponding character template type parameter.

Requirements

No operation listed below on CharTraits may throw an exception.

Given

  • CharT, a character type
  • X, a CharTraits type for type CharT
  • c, d, values of type CharT
  • p, q, values of type const CharT*
  • s, a value of type CharT*
  • n, i, j, values of type std::size_t
  • e, f, values of type X::int_type
  • pos, a value of type X::pos_type
  • state, a value of type X::state_type
  • r, an lvalue of type CharT
ExpressionReturn typeSemanticsComplexity
X::char_typeCharTUsed to refer to the character typeCompile-time
X::int_typeA type that can hold all valid values of X::char_type plus X::eof()Compile-time
X::off_typeInvokes implementation-defined behavior if not std::streamoff when X is used as the traits template parameter in input/output classes.Compile-time
X::pos_type* Functions in input/output classes returning this type use X::pos_type(X::off_type(-1)) as an invalid value to signal an error
* Use of this invalid value as an argument to any std::istream, std::ostream or std::streambuf member taking a value of this type is undefined behavior
* Invokes implementation-defined behavior if this type is not std::streampos when X is used as the traits template parameter in input/output classes
Compile-time
X::state_typeDestructible, CopyAssignable, CopyConstructible, DefaultConstructibleCompile-time
X::eq(c, d)boolReturns: whether c is to be treated as equal to dConstant
X::lt(c, d)boolReturns: whether c is to be treated as less than dConstant
X::compare(p, q, n)intReturns:
* 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)std::size_tReturns: the smallest i such that X::eq(p[i], CharT()) is trueLinear
X::find(p, n, c)const X::char_type*Returns:
* The smallest q in [p, p + n) such that X::eq(*q, c) is true
* 0 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** Requires: [p, p + n) and [s, s + n) do not overlap
* Returns: s
* For each i in [0, n), performs X::assign(s[i], p[i])
Linear
X::assign(r, d)(Not used)Assigns r = dConstant
X::assign(s, n, c)X::char_type** For each i in [0, n), performs X::assign(s[i], c).
* Returns: s
Linear
X::not_eof(e)X::int_type* Returns: e if X::eq_int_type(e, X::eof()) is false
* Otherwise a value f such that X::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_typeReturns: some value e, constrained by the definitions of X::to_char_type and X::eq_int_typeConstant
X::eq_int_type(e, f)bool* For all c and d, X::eq(c, d) is equal to X::eq_int_type(X::to_int_type(c), X::to_int_type(d))
* Returns:
 * Yields X::eq(c, d) if for some c and d, e == X::to_int_type(c) and
  f == X::to_int_type(d)
 * Otherwise, yields true if 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_typeReturns: a value e such that X::eq_int_type(e, X::to_int_type(c)) is false for all values cConstant

Standard library

CharTraits is required by the following standard library class templates as a template type parameter:

Strings

pubbasic_stringstores and manipulates sequences of characters
pubbasic_string_view(C++17)read-only string view

Streams

pubbasic_iosmanages an arbitrary stream buffer
pubbasic_istreamwraps a given abstract device (std::basic_streambuf)and provides high-level input interface
pubbasic_ifstreamimplements high-level file stream input operations
pubbasic_istringstreamimplements high-level string stream input operations
pubbasic_ispanstream(C++23)implements fixed character buffer input operations
pubbasic_ostreamwraps a given abstract device (std::basic_streambuf)and provides high-level output interface
pubbasic_ofstreamimplements high-level file stream output operations
pubbasic_ostringstreamimplements high-level string stream output operations
pubbasic_osyncstream(C++20)synchronized output stream wrapper
pubbasic_ospanstream(C++23)implements fixed character buffer output operations
pubbasic_iostreamwraps a given abstract device (std::basic_streambuf)and provides high-level input/output interface
pubbasic_fstreamimplements high-level file stream input/output operations
pubbasic_stringstreamimplements high-level string stream input/output operations
pubbasic_spanstream(C++23)implements fixed character buffer input/output operations

Stream iterators

pubistream_iteratorinput iterator that reads from std::basic_istream
pubostream_iteratoroutput iterator that writes to std::basic_ostream

Stream buffers

pubbasic_streambufabstracts a raw device
pubbasic_filebufimplements raw file device
pubbasic_stringbufimplements raw string device
pubbasic_syncbuf(C++20)synchronized output device wrapper
pubbasic_spanbuf(C++23)implements raw fixed character buffer device

Stream buffer iterators

pubistreambuf_iteratorinput iterator that reads from std::basic_streambuf
pubostreambuf_iteratoroutput iterator that writes to std::basic_streambuf

CharTraits is satisfied by the following standard library classes:

Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

DRApplied toBehavior as publishedCorrect behavior
LWG 335C++98the requirements on the binary overload of assign did not prevent assignments to rvaluesits first argument can only be an lvalue
LWG 352C++98X::state_type was only required to be CopyConstructibleit is also required to be CopyAssignable and DefaultConstructible
LWG 3085C++98X::copy only required p not in [s, s + n), which is too weak [1]requires [p, p + n) and [s, s + n) not to overlap

[1] [p, p + n) and [s, s + n) can overlap, using std::memcpy to implement X::copy results in undefined behavior in this case.

C++ named requirements:CharTraits

CharTraits is a traits class that abstracts basic character and string operations for a given character type. Most standard library string and input/output classes require a CharTraits template type parameter alongside a corresponding character template type parameter.

Requirements

No operation listed below on CharTraits may throw an exception.

Given

  • CharT, a character type
  • X, a CharTraits type for type CharT
  • c, d, values of type CharT
  • p, q, values of type const CharT*
  • s, a value of type CharT*
  • n, i, j, values of type std::size_t
  • e, f, values of type X::int_type
  • pos, a value of type X::pos_type
  • state, a value of type X::state_type
  • r, an lvalue of type CharT
ExpressionReturn typeSemanticsComplexity
X::char_typeCharTUsed to refer to the character typeCompile-time
X::int_typeA type that can hold all valid values of X::char_type plus X::eof()Compile-time
X::off_typeInvokes implementation-defined behavior if not std::streamoff when X is used as the traits template parameter in input/output classes.Compile-time
X::pos_type* Functions in input/output classes returning this type use X::pos_type(X::off_type(-1)) as an invalid value to signal an error
* Use of this invalid value as an argument to any std::istream, std::ostream or std::streambuf member taking a value of this type is undefined behavior
* Invokes implementation-defined behavior if this type is not std::streampos when X is used as the traits template parameter in input/output classes
Compile-time
X::state_typeDestructible, CopyAssignable, CopyConstructible, DefaultConstructibleCompile-time
X::eq(c, d)boolReturns: whether c is to be treated as equal to dConstant
X::lt(c, d)boolReturns: whether c is to be treated as less than dConstant
X::compare(p, q, n)intReturns:
* 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)std::size_tReturns: the smallest i such that X::eq(p[i], CharT()) is trueLinear
X::find(p, n, c)const X::char_type*Returns:
* The smallest q in [p, p + n) such that X::eq(*q, c) is true
* 0 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** Requires: [p, p + n) and [s, s + n) do not overlap
* Returns: s
* For each i in [0, n), performs X::assign(s[i], p[i])
Linear
X::assign(r, d)(Not used)Assigns r = dConstant
X::assign(s, n, c)X::char_type** For each i in [0, n), performs X::assign(s[i], c).
* Returns: s
Linear
X::not_eof(e)X::int_type* Returns: e if X::eq_int_type(e, X::eof()) is false
* Otherwise a value f such that X::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_typeReturns: some value e, constrained by the definitions of X::to_char_type and X::eq_int_typeConstant
X::eq_int_type(e, f)bool* For all c and d, X::eq(c, d) is equal to X::eq_int_type(X::to_int_type(c), X::to_int_type(d))
* Returns:
 * Yields X::eq(c, d) if for some c and d, e == X::to_int_type(c) and
  f == X::to_int_type(d)
 * Otherwise, yields true if 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_typeReturns: a value e such that X::eq_int_type(e, X::to_int_type(c)) is false for all values cConstant

Standard library

CharTraits is required by the following standard library class templates as a template type parameter:

Strings

pubbasic_stringstores and manipulates sequences of characters
pubbasic_string_view(C++17)read-only string view

Streams

pubbasic_iosmanages an arbitrary stream buffer
pubbasic_istreamwraps a given abstract device (std::basic_streambuf)and provides high-level input interface
pubbasic_ifstreamimplements high-level file stream input operations
pubbasic_istringstreamimplements high-level string stream input operations
pubbasic_ispanstream(C++23)implements fixed character buffer input operations
pubbasic_ostreamwraps a given abstract device (std::basic_streambuf)and provides high-level output interface
pubbasic_ofstreamimplements high-level file stream output operations
pubbasic_ostringstreamimplements high-level string stream output operations
pubbasic_osyncstream(C++20)synchronized output stream wrapper
pubbasic_ospanstream(C++23)implements fixed character buffer output operations
pubbasic_iostreamwraps a given abstract device (std::basic_streambuf)and provides high-level input/output interface
pubbasic_fstreamimplements high-level file stream input/output operations
pubbasic_stringstreamimplements high-level string stream input/output operations
pubbasic_spanstream(C++23)implements fixed character buffer input/output operations

Stream iterators

pubistream_iteratorinput iterator that reads from std::basic_istream
pubostream_iteratoroutput iterator that writes to std::basic_ostream

Stream buffers

pubbasic_streambufabstracts a raw device
pubbasic_filebufimplements raw file device
pubbasic_stringbufimplements raw string device
pubbasic_syncbuf(C++20)synchronized output device wrapper
pubbasic_spanbuf(C++23)implements raw fixed character buffer device

Stream buffer iterators

pubistreambuf_iteratorinput iterator that reads from std::basic_streambuf
pubostreambuf_iteratoroutput iterator that writes to std::basic_streambuf

CharTraits is satisfied by the following standard library classes:

Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

DRApplied toBehavior as publishedCorrect behavior
LWG 335C++98the requirements on the binary overload of assign did not prevent assignments to rvaluesits first argument can only be an lvalue
LWG 352C++98X::state_type was only required to be CopyConstructibleit is also required to be CopyAssignable and DefaultConstructible
LWG 3085C++98X::copy only required p not in [s, s + n), which is too weak [1]requires [p, p + n) and [s, s + n) not to overlap

[1] [p, p + n) and [s, s + n) can overlap, using std::memcpy to implement X::copy results in undefined behavior in this case.