Namespaces
Variants
Views
Actions

std::codecvt

From cppreference.com
< cpp‎ | locale
Revision as of 19:54, 2 November 2012 by P12bot (Talk | contribs)

Template:ddcl list begin <tr class="t-dsc-header">

<td>
Defined in header <locale>
</td>

<td></td> <td></td> <tr class="t-dcl ">

<td class="t-dcl-nopad">
template<

    class InternT,
    class ExternT,
    class State

> class codecvt;
</td>

<td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> Template:ddcl list end

Class 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.

cpp/locale/codecvt basecpp/locale/locale/facetstd-codecvt-inheritance.svg
About this image

Inheritance diagram

Four specializations are provided by the standard library and are implemented by all locale objects created in a C++ program:

Defined in header <locale>
std::codecvt<char, char, std::mbstate_t> identity conversion
std::codecvt<char16_t, char, std::mbstate_t> conversion between UTF-16 and UTF-8 (since C++11)
std::codecvt<char32_t, char, std::mbstate_t> conversion between UTF-32 and UTF-8 (since C++11)
std::codecvt<wchar_t, char, std::mbstate_t> locale-specific conversion between wide string and narrow, possibly multibyte, string

Contents

Member types

Member type Definition
intern_type internT
extern_type externT
state_type stateT

Member objects

Member name Type
id (static) std::locale::id

Member functions

Template:cpp/locale/codecvt/dcl list outTemplate:cpp/locale/codecvt/dcl list inTemplate:cpp/locale/codecvt/dcl list unshiftTemplate:cpp/locale/codecvt/dcl list encodingTemplate:cpp/locale/codecvt/dcl list always noconvTemplate:cpp/locale/codecvt/dcl list lengthTemplate:cpp/locale/codecvt/dcl list max length
constructs a new codecvt facet
(public member function)
destructs a codecvt facet
(protected member function)

Protected member functions

Template:cpp/locale/codecvt/dcl list do outTemplate:cpp/locale/codecvt/dcl list do inTemplate:cpp/locale/codecvt/dcl list do unshiftTemplate:cpp/locale/codecvt/dcl list do encodingTemplate:cpp/locale/codecvt/dcl list do always noconvTemplate:cpp/locale/codecvt/dcl list do lengthTemplate:cpp/locale/codecvt/dcl list do max length

Inherited from std::codecvt_base

Member 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

Example

The following examples reads a UTF-8 file using a locale which implements UTF-8 conversion in codecvt<wchar_t, char, mbstate_t>

#include <iostream>
#include <fstream>
#include <string>
#include <locale>
#include <iomanip>
int main()
{
    // UTF-8 narrow multibyte encoding
    std::ofstream("text.txt") << u8"z\u00df\u6c34\U0001d10b"; // or u8"zß水𝄋"
                                           // or "\x7a\xc3\x9f\xe6\xb0\xb4\xf0\x9d\x84\x8b";
    std::wifstream fin("text.txt");
    fin.imbue(std::locale("en_US.UTF-8")); // this locale's codecvt<wchar_t, char, mbstate_t>
                                           // converts UTF-8 to UCS4
    std::cout << "The UTF-8 file contains the following wide characters: \n";
    for(wchar_t c; fin >> c; )
        std::cout << "U+" << std::hex << std::setw(4) << std::setfill('0') << c << '\n';
}

Output:

The UTF-8 file contains the following wide characters:
U+007a
U+00df
U+6c34
U+1d10b

See also

Character
conversions
narrow multibyte
(char)
UTF-8
(char)
UTF-16
(char16_t)
UTF-16 mbrtoc16 / c16rtomb codecvt<char16_t, char, mbstate_t>
codecvt_utf8_utf16<char16_t>
codecvt_utf8_utf16<char32_t>
codecvt_utf8_utf16<wchar_t>
N/A
UCS2 No codecvt_utf8<char16_t> codecvt_utf16<char16_t>
UTF-32/UCS4
(char32_t)
mbrtoc32 / c32rtomb codecvt<char32_t, char, mbstate_t>
codecvt_utf8<char32_t>
codecvt_utf16<char32_t>
UCS2/UCS4
(wchar_t)
No codecvt_utf8<wchar_t> codecvt_utf16<wchar_t>
wide
(wchar_t)
codecvt<wchar_t, char, mbstate_t>
mbsrtowcs / wcsrtombs
No No
Template:cpp/locale/dcl list codecvt utf8Template:cpp/locale/dcl list codecvt utf16Template:cpp/locale/dcl list codecvt utf8 utf16
defines character conversion errors
(class template)
creates a codecvt facet for the named locale
(class template)