std::codecvt<InternT,ExternT,StateT>:: in, std::codecvt<InternT,ExternT,StateT>:: do_in

If this codecvt facet does not define a conversion, no characters are converted. to_next is set to be equal to to , state is unchanged, and std::codecvt_base::noconv is returned.

do_in ( state, from, from_end, from_next, to, to + 1 , to_next ) must return ok if

• this codecvt facet is used by basic_filebuf , and
• do_in ( state, from, from_end, from_next, to, to_end, to_next ) would return ok where to ! = to_end .

Return value

A value of type std::codecvt_base::result , indicating the success status as follows:

The non-converting specialization std:: codecvt < char , char , std:: mbstate_t > always returns std::codecvt_base::noconv .

Notes

Requires that from <= from_end && to <= to_end and that state either representing the initial shift state or obtained by converting the preceding characters in the sequence.

The effect on state is deliberately unspecified. In standard facets, it is used to maintain shift state like when calling std::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.

Example

#include <iostream>
#include <locale>
#include <string>
 
int main()
{
    std::locale::global(std::locale("en_US.utf8"));
    auto const& 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_convert
    std::mbstate_t mb = std::mbstate_t(); // initial shift state
    std::wstring internal(external.size(), '\0'); 
    const char* 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';
}

The string in wide encoding: zß水𝄋

Defect reports

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

See also