Namespaces
Variants
Views
Actions

Difference between revisions of "cpp/locale/wstring convert"

From cppreference.com
< cpp‎ | locale
m (own sidebar)
(Added the exposition-only members.)
 
(19 intermediate revisions by 5 users not shown)
Line 1: Line 1:
−
{{cpp/title | wstring_convert}}
+
{{cpp/title|wstring_convert}}
−
{{cpp/locale/wstring_convert/sidebar}}
+
{{cpp/locale/wstring_convert/navbar}}
−
{{ddcl list begin}}
+
{{ddcl|header=locale|since=c++11|deprecated=c++17|removed=c++26|1=
−
{{ddcl list header | locale}}
+
template<
−
{{ddcl list item | notes={{mark c++11 feature}} | 1=
+
    class Codecvt,
−
template< class Codecvt,
+
    class Elem = wchar_t,
−
          class Elem = wchar_t,
+
    class Wide_alloc = std::allocator<Elem>,
−
          class Wide_alloc = std::allocator<Elem>,
+
    class Byte_alloc = std::allocator<char>
−
          class Byte_alloc = std::allocator<char> >
+
> class wstring_convert;
−
class wstring_convert;
+
 
}}
 
}}
−
{{ddcl list end}}
 
  
−
Class template {{cpp|std::wstring_convert}} performs conversions between byte string {{cpp|std::string}} and wide string {{cpp|std::basic_string<Elem>}}, using an individual code conversion facet {{tt|Codecvt}}. {{cpp|std::wstring_convert}} assumes ownership of the conversion facet, and cannot use a facet managed by a locale. The standard facets suitable for use with {{cpp|std::wstring_convert}} are {{cpp|std::codecvt_utf8}} for UTF-8/UCS2 and UTF-8/UCS4 conversions and {{cpp|std::codecvt_utf8_utf16}} for UTF-8/UTF-16 conversions.
+
Class template {{tt|std::wstring_convert}} performs conversions between byte string {{lc|std::string}} and wide string {{c/core|std::basic_string<Elem>}}, using an individual code conversion facet {{tt|Codecvt}}. {{tt|std::wstring_convert}} assumes ownership of the conversion facet, and cannot use a facet managed by a locale.
  
−
===Member types===
+
The standard facets suitable for use with {{tt|std::wstring_convert}} are {{lc|std::codecvt_utf8}} for UTF-8/UCS-2 and UTF-8/UCS-4 conversions and {{lc|std::codecvt_utf8_utf16}} for UTF-8/UTF-16 conversions.
−
{{tdcl list begin}}
+
−
{{tdcl list hitem | Member type | Definition}}
+
−
{{tdcl list item | {{tt|byte_string}} | {{tt|std::basic_string<char, char_traits<char>, Byte_alloc>}}}}
+
−
{{tdcl list item | {{tt|wide_string}} | {{tt|std::basic_string<Elem, char_traits<Elem>, Wide_alloc>}}}}
+
−
{{tdcl list item | {{tt|state_type}} | {{tt|Codecvt::state_type}}}}
+
−
{{tdcl list item | {{tt|int_type}} | {{tt|wide_string::traits_type::int_type}}}}
+
−
{{tdcl list end}}
+
  
−
===Member functions===
+
===Nested types===
−
{{dcl list begin}}
+
{{dsc begin}}
−
{{dcl list mem ctor | cpp/locale/wstring_convert/wstring_convert | constructs a new wstring_convert }}
+
{{dsc hitem|Type|Definition}}
−
{{dcl list mem dtor | cpp/locale/wstring_convert/~wstring_convert | destructs the wstring_convert and its conversion facet}}
+
{{dsc|{{tt|byte_string}}|{{c/core|std::basic_string<char, std::char_traits<char>, Byte_alloc>}}}}
−
{{dcl list mem fun | cpp/locale/wstring_convert/from_bytes | converts a byte string into a wide string }}
+
{{dsc|{{tt|wide_string}}|{{c/core|std::basic_string<Elem, std::char_traits<Elem>, Wide_alloc>}}}}
−
{{dcl list mem fun | cpp/locale/wstring_convert/to_bytes | converts a wide string into a byte string }}
+
{{dsc|{{tt|state_type}}|{{c/core|typename Codecvt::state_type}}}}
−
{{dcl list mem fun | cpp/locale/wstring_convert/converted | returns the number of input characters successfully converted }}
+
{{dsc|{{tt|int_type}}|{{c/core|typename wide_string::traits_type::int_type}}}}
−
{{dcl list mem fun | cpp/locale/wstring_convert/state | returns the current shift state }}
+
{{dsc end}}
−
{{dcl list end}}
+
  
−
===Example===
+
===Data members===
 +
{{dsc begin}}
 +
{{dsc hitem|Member|Description}}
 +
{{dsc expos mem obj|spec={{tt|byte_string}}|byte_err_string|id=byte_err_string|the byte string to display on errors}}
 +
{{dsc expos mem obj|spec={{tt|wide_string}}|wide_err_string|id=wide_err_string|the wide string to display on errors}}
 +
{{dsc expos mem obj|spec={{c/core|Codecvt*}}|cvtptr|id=cvtptr|a pointer to the allocated conversion object}}
 +
{{dsc expos mem obj|spec={{tt|state_type}}|cvtstate|id=cvtstate|the conversion state object}}
 +
{{dsc expos mem obj|spec={{c/core|std::size_t}}|cvtcount|id=cvtcount|the conversion count}}
 +
{{dsc end}}
  
−
{{example cpp
+
===Member functions===
−
|  
+
{{dsc begin}}
−
| code=
+
{{dsc inc|cpp/locale/wstring_convert/dsc wstring_convert}}
−
#include <iostream>
+
{{dsc mem fun|nolink=true|operator{{=}}|the copy assignment operator is deleted}}
−
#include <string>
+
{{dsc inc|cpp/locale/wstring_convert/dsc ~wstring_convert}}
−
#include <locale>
+
{{dsc inc|cpp/locale/wstring_convert/dsc from_bytes}}
−
#include <codecvt>
+
{{dsc inc|cpp/locale/wstring_convert/dsc to_bytes}}
−
int main()
+
{{dsc inc|cpp/locale/wstring_convert/dsc converted}}
−
{
+
{{dsc inc|cpp/locale/wstring_convert/dsc state}}
−
    // UTF-8 data: letter 'z', CJK ideogram 'water', musical sign 'segno'
+
{{dsc end}}
−
    std::string utf8 = u8"z\u6c34\U0001d10b";
+
−
 
+
−
    // the UTF-8 / UTF-16 standard conversion facet
+
−
    std::wstring_convert<std::codecvt_utf8_utf16<char16_t>, char16_t> utf16conv;
+
−
    std::u16string utf16 = utf16conv.from_bytes(utf8);
+
−
    std::cout << "UTF16 conversion produced " << utf16.size() << " code points:\n";
+
−
    for(char16_t c : utf16)
+
−
        std::cout << std::hex << std::showbase << c << '\n';
+
−
 
+
−
    // the UTF-8 / UTF-32 standard conversion facet
+
−
    std::wstring_convert<std::codecvt_utf8<char32_t>, char32_t> utf32conv;
+
−
    std::u32string utf32 = utf32conv.from_bytes(utf8);
+
−
    std::cout << "UTF32 conversion produced " << std::dec << utf32.size() << " code points:\n";
+
−
    for(char32_t c : utf32)
+
−
        std::cout << std::hex << std::showbase << c << '\n';
+
−
}
+
−
| output=
+
−
UTF16 conversion produced 4 code points:
+
−
0x7a
+
−
0x6c34
+
−
0xd834
+
−
0xdd0b
+
−
UTF32 conversion produced 3 code points:
+
−
0x7a
+
−
0x6c34
+
−
0x1d10b
+
−
}}
+
  
 
===See also===
 
===See also===
 
{{cpp/locale/unicode string conversions}}
 
{{cpp/locale/unicode string conversions}}
−
{{dcl list begin}}
+
{{dsc begin}}
−
{{dcl list template | cpp/locale/dcl list wbuffer_convert}}
+
{{dsc inc|cpp/locale/dsc wbuffer_convert}}
−
{{dcl list template | cpp/locale/dcl list codecvt_utf8}}
+
{{dsc inc|cpp/locale/dsc codecvt_utf8}}
−
{{dcl list template | cpp/locale/dcl list codecvt_utf8_utf16}}
+
{{dsc inc|cpp/locale/dsc codecvt_utf8_utf16}}
−
{{dcl list end}}
+
{{dsc end}}
 +
 
 +
{{langlinks|de|es|fr|it|ja|pt|ru|zh}}

Latest revision as of 23:34, 20 October 2024

 
C++
 
Localization library
 
std::wstring_convert
 
Defined in header <locale>
template<

    class Codecvt,
    class Elem = wchar_t,
    class Wide_alloc = std::allocator<Elem>,
    class Byte_alloc = std::allocator<char>

> class wstring_convert;
 (since C++11)
(deprecated in C++17)
(removed in C++26)

Class template std::wstring_convert performs conversions between byte string std::string and wide string std::basic_string<Elem>, using an individual code conversion facet Codecvt. std::wstring_convert assumes ownership of the conversion facet, and cannot use a facet managed by a locale.

The standard facets suitable for use with std::wstring_convert are std::codecvt_utf8 for UTF-8/UCS-2 and UTF-8/UCS-4 conversions and std::codecvt_utf8_utf16 for UTF-8/UTF-16 conversions.

Contents

[edit] Nested types

Type Definition
byte_string std::basic_string<char, std::char_traits<char>, Byte_alloc>
wide_string std::basic_string<Elem, std::char_traits<Elem>, Wide_alloc>
state_type typename Codecvt::state_type
int_type typename wide_string::traits_type::int_type

[edit] Data members

Member Description
byte_string byte_err_string the byte string to display on errors
(exposition-only member object*)
wide_string wide_err_string the wide string to display on errors
(exposition-only member object*)
Codecvt* cvtptr a pointer to the allocated conversion object
(exposition-only member object*)
state_type cvtstate the conversion state object
(exposition-only member object*)
std::size_t cvtcount the conversion count
(exposition-only member object*)

[edit] Member functions

 constructs a new wstring_convert
(public member function) [edit]
operator=
 the copy assignment operator is deleted
(public member function)
destructs the wstring_convert and its conversion facet
(public member function) [edit]
converts a byte string into a wide string
(public member function) [edit]
converts a wide string into a byte string
(public member function) [edit]
returns the number of characters successfully converted
(public member function) [edit]
returns the current conversion state
(public member function) [edit]

[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>
(C++11)(deprecated in C++17)(removed in C++26)
 performs conversion between a byte stream buffer and a wide stream buffer
(class template) [edit]
(C++11)(deprecated in C++17)(removed in C++26)
 converts between UTF-8 and UCS-2/UCS-4
(class template) [edit]
(C++11)(deprecated in C++17)(removed in C++26)
 converts between UTF-8 and UTF-16
(class template) [edit]
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/locale/wstring_convert&oldid=177197"