| Localization library | |||||||||||||||||||||||||
| Regular expressions library(C++11) | |||||||||||||||||||||||||
| Formatting library(C++20) | |||||||||||||||||||||||||
| Null-terminated sequence utilities | |||||||||||||||||||||||||
| Byte strings | |||||||||||||||||||||||||
| Multibyte strings | |||||||||||||||||||||||||
| Wide strings | |||||||||||||||||||||||||
| Primitive numeric conversions | |||||||||||||||||||||||||
| |||||||||||||||||||||||||
| Text encoding identifications | |||||||||||||||||||||||||
| |||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Member functions | ||||
codecvt::incodecvt::do_in | ||||
Defined in header <locale> | ||
public: result in( StateT& state, | (1) | |
protected: virtual result do_in( StateT& state, | (2) | |
do_in of the most derived class.codecvt facet defines a conversion, translates the external characters from the source range[from, from_end) to internal characters, placing the results in the subsequent locations starting atto. Converts no more thanfrom_end- from external characters and writes no more thanto_end- to internal characters. Leavesfrom_next andto_next pointing one beyond the last element successfully converted.If thiscodecvt facet does not define a conversion, no characters are converted.to_next is set to be equal toto,state is unchanged, andstd::codecvt_base::noconv is returned.
do_in(state, from, from_end, from_next, to, to+1, to_next) must returnok if
codecvt facet is used bybasic_filebuf, andok whereto!= to_end.Contents |
A value of typestd::codecvt_base::result, indicating the success status as follows:
ok | conversion completed |
partial | not enough space in the output buffer or unexpected end of source buffer |
error | encountered a character that could not be converted |
noconv | this facet is non-converting, no output written |
The non-converting specializationstd::codecvt<char,char,std::mbstate_t> always returnsstd::codecvt_base::noconv.
Requires thatfrom<= from_end&& to<= to_end and thatstate either representing the initial shift state or obtained by converting the preceding characters in the sequence.
The effect onstate is deliberately unspecified. In standard facets, it is used to maintain shift state like when callingstd::mbsrtowcs, and is therefore updated to reflect the conversion state after the last processed external character, but a user-defined facet is free to use it to maintain any other state, e.g. count the number of special characters encountered.
#include <iostream>#include <locale>#include <string> int main(){std::locale::global(std::locale("en_US.utf8"));autoconst& f=std::use_facet<std::codecvt<wchar_t,char,std::mbstate_t>>(std::locale());std::string external="z\u00df\u6c34\U0001d10b";// or u8"zß水𝄋"// or "\x7a\xc3\x9f\xe6\xb0\xb4\xf0\x9d\x84\x8b" // note that the following can be done with wstring_convertstd::mbstate_t mb=std::mbstate_t();// initial shift statestd::wstring internal(external.size(),'\0');constchar* from_next;wchar_t* to_next; f.in(mb,&external[0],&external[external.size()], from_next,&internal[0],&internal[internal.size()], to_next);// error checking skipped for brevity internal.resize(to_next-&internal[0]); std::wcout<< L"The string in wide encoding: "<< internal<<'\n';}
Output:
The string in wide encoding: zß水𝄋
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
| DR | Applied to | Behavior as published | Correct behavior |
|---|---|---|---|
| LWG 76 | C++98 | it was unclear whether the conversion is required to support producing one internal character at a time | only required if used bybasic_filebuf |
[virtual] | reads from the associated file (virtual protected member function of std::basic_filebuf<CharT,Traits>)[edit] |
| converts a byte string into a wide string (public member function of std::wstring_convert<Codecvt,Elem,Wide_alloc,Byte_alloc>)[edit] | |
| converts a narrow multibyte character string to wide string, given state (function)[edit] | |
[virtual] | converts a string fromInternT toExternT, such as when writing to file(virtual protected member function)[edit] |
