std::codecvt

Class template std::codecvt encapsulates conversion of character strings, including wide and multibyte, from one encoding to another. All file I/O operations performed through std::basic_fstream <CharT> use the std::codecvt<CharT, char, std::mbstate_t > facet of the locale imbued in the stream.

std-codecvt-inheritance.svg

Inheritance diagram

Inherited from std::codecvt_base

Nested type Definition

enum result { ok, partial, error, noconv }; Unscoped enumeration type

Enumeration constant Definition

ok conversion was completed with no error

partial not all source characters were converted

error encountered an invalid character

noconv no conversion required, input and output types are the same

[edit] Example

The following examples reads a UTF-8 file using a locale which implements UTF-8 conversion in codecvt<wchar_t, char, std::mbstate_t > and converts a UTF-8 string to UTF-16 using one of the standard specializations of std::codecvt.

Run this code

#include <codecvt>
#include <cstdint>
#include <fstream>
#include <iomanip>
#include <iostream>
#include <locale>
#include <string>
 
// utility wrapper to adapt locale-bound facets for wstring/wbuffer convert
template<class Facet>
struct deletable_facet : Facet
{
 template<class... Args>
 deletable_facet(Args&&... args) : Facet(std::forward <Args>(args)...) {}
 ~deletable_facet() {}
};
 
int main()
{
 // UTF-8 narrow multibyte encoding
 std::string data = reinterpret_cast<const char*>(+u8"z\u00df\u6c34\U0001f34c");
 // or reinterpret_cast<const char*>(+u8"zß水🍌")
 // or "\x7a\xc3\x9f\xe6\xb0\xb4\xf0\x9f\x8d\x8c"
 
 std::ofstream ("text.txt") << data;
 
 // using system-supplied locale's codecvt facet
 std::wifstream fin("text.txt");
 // reading from wifstream will use codecvt<wchar_t, char, std::mbstate_t>
 // this locale's codecvt converts UTF-8 to UCS4 (on systems such as Linux)
 fin.imbue(std::locale ("en_US.UTF-8"));
 std::cout << "The UTF-8 file contains the following UCS4 code units:\n" << std::hex ;
 for (wchar_t c; fin >> c;)
 std::cout << "U+" << std::setw (4) << std::setfill ('0')
 << static_cast<uint32_t>(c) << ' ';
 
 // using standard (locale-independent) codecvt facet
 std::wstring_convert <
 deletable_facet<std::codecvt<char16_t, char, std::mbstate_t >>, char16_t> conv16;
 std::u16string str16 = conv16.from_bytes(data);
 
 std::cout << "\n\nThe UTF-8 file contains the following UTF-16 code units:\n"
 << std::hex ;
 for (char16_t c : str16)
 std::cout << "U+" << std::setw (4) << std::setfill ('0')
 << static_cast<uint16_t>(c) << ' ';
 std::cout << '\n';
}

Output:

The UTF-8 file contains the following UCS4 code units:
U+007a U+00df U+6c34 U+1f34c 
 
The UTF-8 file contains the following UTF-16 code units:
U+007a U+00df U+6c34 U+d83c U+df4c

[edit] Defect reports

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

DR	Applied to	Behavior as published	Correct behavior
LWG 3767	C++20	std::codecvt<char16_t, char8_t, std::mbstate_t > and std::codecvt<char32_t, char8_t, std::mbstate_t > are locale-independent	deprecated them

[edit] See also

Character conversions	locale-defined multibyte (UTF-8, GB18030)	UTF-8	UTF-16
UTF-16	`mbrtoc16` / `c16rtomb` (with C11's DR488)	`codecvt`<char16_t,char,mbstate_t> `codecvt_utf8_utf16` <char16_t> `codecvt_utf8_utf16` <char32_t> `codecvt_utf8_utf16` <wchar_t>	N/A
UCS-2	`c16rtomb` (without C11's DR488)	`codecvt_utf8` <char16_t>	`codecvt_utf16` <char16_t>
UTF-32	`mbrtoc32` / `c32rtomb`	`codecvt`<char32_t,char,mbstate_t> `codecvt_utf8` <char32_t>	`codecvt_utf16` <char32_t>
system wchar_t: UTF-32 (non-Windows) UCS-2 (Windows)	`mbsrtowcs` / `wcsrtombs` `use_facet` <`codecvt` <wchar_t,char,mbstate_t>>(`locale`)	`codecvt_utf8` <wchar_t>	`codecvt_utf16` <wchar_t>