# std::codecvt<InternT,ExternT,State>::in, std::codecvt<InternT,ExternT,State>::do_in

From cppreference.com
< cpp‎ | locale‎ | codecvt

Defined in header `<locale>` |  |
public: result in( StateT& state, const ExternT* from, const ExternT* from_end, const ExternT*& from_next, InternT* to, InternT* to_end, InternT*& to_next ) const; | (1) |
protected: virtual result do_in( StateT& state, const ExternT* from, const ExternT* from_end, const ExternT*& from_next, InternT* to, InternT* to_end, InternT*& to_next ) const; | (2) |

1) Public member function, calls the member function `do_in` of the most derived class.
2) If this `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 at `to`. Converts no more than from_end - from external characters and writes no more than to_end - to internal characters. Leaves `from_next` and `to_next` pointing one beyond the last element successfully converted.

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.

### Return value

A value of type std::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 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

Run this code

    #include <iostream>
    #include <string>
    #include <locale>

    int main()
    {
        std::locale::global(std::locale("en_US.utf8"));
        auto& f = std::use_facet<std::codecvt<wchar_t, char, std::mbstate_t>>(std::locale());
        std::string external = u8"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';
    }

Output:

    The string in wide encoding: zß水𝄋

### See also

underflow [virtual] | reads from the associated file (virtual protected member function of `std::basic_filebuf<CharT,Traits>`)
from_bytes | converts a byte string into a wide string (public member function of `std::wstring_convert<Codecvt,Elem,Wide_alloc,Byte_alloc>`)
mbsrtowcs | converts a narrow multibyte character string to wide string, given state (function)
do_out [virtual] | converts a string from internT to externT, such as when writing to file (virtual protected member function)

Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/locale/codecvt/in&oldid=111108"