std::codecvt_mode

 

C++

Language

Standard Library Headers

Freestanding and hosted implementations

Named requirements

Language support library

Concepts library (C++20)

Diagnostics library

Utilities library

Strings library

Containers library

Iterators library

Ranges library (C++20)

Algorithms 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

 

Defined in header <codecvt>
enum codecvt_mode {     consume_header = 4,     generate_header = 2,     little_endian = 1 };		(since C++11) (deprecated in C++17)

The facets std::codecvt_utf8, std::codecvt_utf16, and std::codecvt_utf8_utf16 accept an optional value of type std::codecvt_mode as a template argument, which specifies optional features of the unicode string conversion.

Constants

Defined in header <locale>
Value	Meaning
little_endian	assume the input is in little-endian byte order (applies to UTF-16 input only, the default is big-endian)
consume_header	consume the byte order mark, if present at the start of input sequence, and (in case of UTF-16), rely on the byte order it specifies for decoding the rest of the input
generate_header	output the byte order mark at the start of the output sequence

The recognized byte order marks are:

0xfe 0xff	UTF-16 big-endian
0xff 0xfe	UTF-16 little-endian
0xef 0xbb 0xbf	UTF-8 (no effect on endianness)

If std::consume_header is not selected when reading a file beginning with byte order mark, the Unicode character U+FEFF (Zero width non-breaking space) will be read as the first character of the string content.

Example

The following example demonstrates consuming the UTF-8 BOM

Run this code

#include <fstream>
#include <iostream>
#include <string>
#include <locale>
#include <codecvt>
 
int main()
{
    // UTF-8 data with BOM
    std::ofstream("text.txt") << u8"\ufeffz\u6c34\U0001d10b";
    // read the UTF8 file, skipping the BOM
    std::wifstream fin("text.txt");
    fin.imbue(std::locale(fin.getloc(),
                          new std::codecvt_utf8<wchar_t, 0x10ffff, std::consume_header>));
    for (wchar_t c; fin.get(c); )
        std::cout << std::hex << std::showbase << c << '\n';
}

Output:

0x7a
0x6c34
0x1d10b

See also

codecvt	converts between character encodings, including UTF-8, UTF-16, UTF-32 (class template)
codecvt_utf8 (C++11)(deprecated in C++17)	converts between UTF-8 and UCS2/UCS4 (class template)
codecvt_utf16 (C++11)(deprecated in C++17)	converts between UTF-16 and UCS2/UCS4 (class template)
codecvt_utf8_utf16 (C++11)(deprecated in C++17)	converts between UTF-8 and UTF-16 (class template)