| Localization library | |||||||||||||||||||||||||
| Regular expressions library(C++11) | |||||||||||||||||||||||||
| Formatting library(C++20) | |||||||||||||||||||||||||
| Null-terminated sequence utilities | |||||||||||||||||||||||||
| Byte strings | |||||||||||||||||||||||||
| Multibyte strings | |||||||||||||||||||||||||
| Wide strings | |||||||||||||||||||||||||
| Primitive numeric conversions | |||||||||||||||||||||||||
| |||||||||||||||||||||||||
| Text encoding identifications | |||||||||||||||||||||||||
| |||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Defined in header <locale> | ||
template<class InternT,class ExternT,class State> class codecvt_byname:publicstd::codecvt<InternT, ExternT, State>; | ||
std::codecvt_byname is astd::codecvt facet which encapsulates multibyte/wide character conversion rules of a locale specified at its construction.
Contents |
The standard library is guaranteed to provide the following specializations:
Defined in header <locale> | |
| std::codecvt_byname<char,char,std::mbstate_t> | identity conversion |
| std::codecvt_byname<char16_t,char,std::mbstate_t> (since C++11)(deprecated in C++20) | conversion between UTF-16 and UTF-8 |
| std::codecvt_byname<char16_t, char8_t,std::mbstate_t> (since C++20) | conversion between UTF-16 and UTF-8 |
| std::codecvt_byname<char32_t,char,std::mbstate_t> (since C++11)(deprecated in C++20) | conversion between UTF-32 and UTF-8 |
| std::codecvt_byname<char32_t, char8_t,std::mbstate_t> (since C++20) | conversion between UTF-32 and UTF-8 |
| std::codecvt_byname<wchar_t,char,std::mbstate_t> | locale-specific conversion between wide string and narrow character sets |
(constructor) | constructs a newcodecvt_byname facet(public member function)[edit] |
(destructor) | destroys acodecvt_byname facet(protected member function)[edit] |
explicit codecvt_byname(constchar* name,std::size_t refs=0); | ||
explicit codecvt_byname(conststd::string& name,std::size_t refs=0); | (since C++11) | |
Constructs a newstd::codecvt_byname facet for a locale withname.
refs is used for resource management: ifrefs==0, the implementation destroys the facet, when the laststd::locale object holding it is destroyed. Otherwise, the object is not destroyed.
| name | - | the name of the locale |
| refs | - | the number of references that link to the facet |
protected: ~codecvt_byname(); | ||
Destroys the facet.
| Type | Definition |
intern_type | internT |
extern_type | externT |
state_type | stateT |
| Member | Description |
std::locale::idid[static] | the identifier of thefacet |
invokesdo_out(public member function of std::codecvt<InternT,ExternT,StateT>)[edit] | |
invokesdo_in(public member function of std::codecvt<InternT,ExternT,StateT>)[edit] | |
invokesdo_unshift(public member function of std::codecvt<InternT,ExternT,StateT>)[edit] | |
invokesdo_encoding(public member function of std::codecvt<InternT,ExternT,StateT>)[edit] | |
invokesdo_always_noconv(public member function of std::codecvt<InternT,ExternT,StateT>)[edit] | |
invokesdo_length(public member function of std::codecvt<InternT,ExternT,StateT>)[edit] | |
invokesdo_max_length(public member function of std::codecvt<InternT,ExternT,StateT>)[edit] |
[virtual] | converts a string fromInternT toExternT, such as when writing to file(virtual protected member function of std::codecvt<InternT,ExternT,StateT>)[edit] |
[virtual] | converts a string fromExternT toInternT, such as when reading from file(virtual protected member function of std::codecvt<InternT,ExternT,StateT>)[edit] |
[virtual] | generates the termination character sequence ofExternT characters for incomplete conversion(virtual protected member function of std::codecvt<InternT,ExternT,StateT>)[edit] |
[virtual] | returns the number ofExternT characters necessary to produce oneInternT character, if constant(virtual protected member function of std::codecvt<InternT,ExternT,StateT>)[edit] |
[virtual] | tests if the facet encodes an identity conversion for all valid argument values (virtual protected member function of std::codecvt<InternT,ExternT,StateT>)[edit] |
[virtual] | calculates the length of theExternT string that would be consumed by conversion into givenInternT buffer(virtual protected member function of std::codecvt<InternT,ExternT,StateT>)[edit] |
[virtual] | returns the maximum number ofExternT characters that could be converted into a singleInternT character(virtual protected member function of std::codecvt<InternT,ExternT,StateT>)[edit] |
| 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 |
This example demonstrates reading a GB18030-encoded file using the codecvt facet from a GB18030-aware locale.
#include <fstream>#include <iostream>#include <locale>#include <string> int main(){// GB18030 narrow multibyte encodingstd::ofstream("text.txt")<<"\x7a"// letter 'z', U+007a"\x81\x30\x89\x38"// letter 'ß', U+00df"\xcb\xae"// CJK ideogram '水' (water), U+6c34"\x94\x32\xbc\x35";// musical sign '𝄋' (segno), U+1d10b std::wifstream fin("text.txt"); fin.imbue(std::locale(fin.getloc(), new std::codecvt_byname<wchar_t,char,std::mbstate_t>("zh_CN.gb18030"))); for(wchar_t c; fin.get(c);)std::cout<<std::hex<<std::showbase<<static_cast<unsigned>(c)<<'\n';}
Possible output:
0x7a0xdf0x6c340x1d10b
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
| DR | Applied to | Behavior as published | Correct behavior |
|---|---|---|---|
| LWG 21 | C++98 | the standard library did not need to provide any std::codecvt_byname specializations | two specializations are required |
| converts between character encodings, including UTF-8, UTF-16, UTF-32 (class template)[edit] |
