std::codecvt::in, std::codecvt::do_in

C++

Language

Headers

Freestanding and hosted implementations

Named requirements

Language support library

Concepts library (C++20)

Diagnostics library

Utilities library

Strings library

Containers library

Algorithms library

Iterators library

Numerics library

Input/output library

Localizations library

Regular expressions library (C++11)

Atomic operations library (C++11)

Thread support library (C++11)

Filesystem library (C++17)

Technical Specifications

Localizations library

Locales and facets
locale
use_facet	has_facet
Character classification
isspace isblank (C++11) iscntrl isupper islower isalpha	isdigit ispunct isxdigit isalnum isprint isgraph
Conversions
toupper tolower	wstring_convert (C++11) wbuffer_convert (C++11)
Facet category base classes
ctype_base codecvt_base messages_base	time_base money_base
Facet categories
ctype ctype<char> codecvt collate messages time_get time_put	num_get num_put numpunct money_get money_put moneypunct
Locale-specific facets
ctype_byname codecvt_byname messages_byname collate_byname	time_get_byname time_put_byname numpunct_byname moneypunct_byname
Code conversion facets
codecvt_utf8 (C++11) codecvt_utf16 (C++11)	codecvt_utf8_utf16 (C++11) codecvt_mode (C++11)
C locale
setlocale localeconv lconv	LC_ALLLC_COLLATELC_CTYPELC_MONETARYLC_NUMERICLC_TIME

std::codecvt

Member functions

codecvt::codecvt

codecvt::~codecvt

codecvt::outcodecvt::do_out

codecvt::incodecvt::do_in

codecvt::unshiftcodecvt::do_unshift

codecvt::encodingcodecvt::do_encoding

codecvt::always_noconvcodecvt::do_always_noconv

codecvt::lengthcodecvt::do_length

codecvt::max_lengthcodecvt::do_max_length

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)
from_bytes	converts a byte string into a wide string (public member function of std::wstring_convert)
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)