home | help 
std::codecvt_utf8_utf16(3)     C++ Standard Libary    std::codecvt_utf8_utf16(3)

NAME
     std::codecvt_utf8_utf16 - std::codecvt_utf8_utf16

Synopsis
	Defined in header <codecvt>
	template<

	    class Elem, 					(since C++11)
	    unsigned  long  Maxcode = 0x10ffff, 		  (deprecated in
     C++17)
	    std::codecvt_mode Mode  =  (std::codecvt_mode)0  >	    (removed  in
     C++26)
	class codecvt_utf8_utf16

	    : public std::codecvt<Elem, char, std::mbstate_t>;

	std::codecvt_utf8_utf16  is a std::codecvt facet which encapsulates con-
     version
	between a UTF-8 encoded byte string and UTF-16 encoded character string.
     If Elem is
	a 32-bit type, one UTF-16 code unit will be stored in each 32-bit  char-
     acter of the
	output sequence.

	This  is  an  N:M  conversion  facet,  and  cannot be used with std::ba-
     sic_filebuf (which
	only permits 1:N conversions, such as UTF-32/UTF-8, between the internal
     and the
	external encodings). This facet can be used with std::wstring_convert.

Template Parameters
	Elem	- either char16_t, char32_t, or wchar_t
	Maxcode - the largest value of Elem that this facet will read  or  write
     without error
	Mode	- a constant of type std::codecvt_mode

Member functions
	constructor   constructs a new codecvt_utf8_utf16 facet
		      (public member function)
	destructor    destroys a codecvt_utf8_utf16 facet
		      (public member function)

     std::codecvt_utf8_utf16::codecvt_utf8_utf16

	explicit codecvt_utf8_utf16( std::size_t refs = 0 );

	Constructs  a new std::codecvt_utf8_utf16 facet, passes the initial ref-
     erence counter
	refs to the base class.

Parameters
	refs - the number of references that link to the facet

     std::codecvt_utf8_utf16::~codecvt_utf8_utf16

	~codecvt_utf8_utf16();

	Destroys the facet. Unlike the locale-managed facets, this  facet's  de-
     structor is
	public.

     Inherited from std::codecvt

Member types
	Member name Definition
	intern_type internT
	extern_type externT
	state_type  stateT

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

Member functions
		      invokes do_out
	out		(public   member  function  of	std::codecvt<InternT,Ex-
     ternT,StateT>)

		      invokes do_in
	in	       (public	member	function   of	std::codecvt<InternT,Ex-
     ternT,StateT>)

		      invokes do_unshift
	unshift 	(public   member  function  of	std::codecvt<InternT,Ex-
     ternT,StateT>)

		      invokes do_encoding
	encoding       (public	member	function   of	std::codecvt<InternT,Ex-
     ternT,StateT>)

		      invokes do_always_noconv
	always_noconv	(public   member  function  of	std::codecvt<InternT,Ex-
     ternT,StateT>)

		      invokes do_length
	length	       (public	member	function   of	std::codecvt<InternT,Ex-
     ternT,StateT>)

		      invokes do_max_length
	max_length	(public   member  function  of	std::codecvt<InternT,Ex-
     ternT,StateT>)

Protected member functions
			 converts a string from InternT to ExternT, such as when
     writing to
	do_out		 file
	[virtual]	 (virtual protected member function of
			 std::codecvt<InternT,ExternT,StateT>)
			 converts a string from ExternT to InternT, such as when
     reading
	do_in		 from file
	[virtual]	 (virtual protected member function of
			 std::codecvt<InternT,ExternT,StateT>)
			 generates the termination character sequence of ExternT
     characters
	do_unshift	 for incomplete conversion
	[virtual]	 (virtual protected member function of
			 std::codecvt<InternT,ExternT,StateT>)
			 returns the number of ExternT characters  necessary  to
     produce one
	do_encoding	 InternT character, if constant
	[virtual]	 (virtual protected member function of
			 std::codecvt<InternT,ExternT,StateT>)
			 tests	if  the facet encodes an identity conversion for
     all valid
	do_always_noconv argument values
	[virtual]	 (virtual protected member function of
			 std::codecvt<InternT,ExternT,StateT>)
			 calculates the length of the ExternT string that  would
     be consumed
	do_length	 by conversion into given InternT buffer
	[virtual]	 (virtual protected member function of
			 std::codecvt<InternT,ExternT,StateT>)
			 returns  the  maximum number of ExternT characters that
     could be
	do_max_length	 converted into a single InternT character
	[virtual]	 (virtual protected member function of
			 std::codecvt<InternT,ExternT,StateT>)

     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
     // Run this code

      #include <cassert>
      #include <codecvt>
      #include <cstdint>
      #include <iostream>
      #include <locale>
      #include <string>

      int main()
      {
	  std::string u8 = "z\u00df\u6c34\U0001f34c";
	  std::u16string u16 = u"z\u00df\u6c34\U0001f34c";

	  // UTF-8 to UTF-16/char16_t
	  std::u16string u16_conv = std::wstring_convert<
	      std::codecvt_utf8_utf16<char16_t>, char16_t>{}.from_bytes(u8);
	  assert(u16 == u16_conv);
	  std::cout << "UTF-8 to UTF-16 conversion produced " << u16_conv.size()
		    << " code units:\n" << std::showbase << std::hex;
	  for (char16_t c : u16_conv)
	      std::cout << static_cast<std::uint16_t>(c) << ' ';

	  // UTF-16/char16_t to UTF-8
	  std::string u8_conv = std::wstring_convert<
	      std::codecvt_utf8_utf16<char16_t>, char16_t>{}.to_bytes(u16);
	  assert(u8 == u8_conv);
	  std::cout << "\nUTF-16 to UTF-8 conversion produced "
		    << std::dec << u8_conv.size() << " bytes:\n" << std::hex;
	  for (char c : u8_conv)
	      std::cout << +static_cast<unsigned char>(c) << ' ';
	  std::cout << '\n';
      }

Output:
      UTF-8 to UTF-16 conversion produced 5 code units:
      0x7a 0xdf 0x6c34 0xd83c 0xdf4c
      UTF-16 to UTF-8 conversion produced 10 bytes:
      0x7a 0xc3 0x9f 0xe6 0xb0 0xb4 0xf0 0x9f 0x8d 0x8c

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

			      converts between	character  encodings,  including
     UTF-8, UTF-16,
	codecvt 	      UTF-32
			      (class template)
	codecvt_mode
	(C++11) 	       tags  to  alter	behavior of the standard codecvt
     facets
	(deprecated in C++17) (enum)
	(removed in C++26)
	codecvt_utf8
	(C++11) 	      converts between UTF-8 and UCS-2/UCS-4
	(deprecated in C++17) (class template)
	(removed in C++26)
	codecvt_utf16
	(C++11) 	      converts between UTF-16 and UCS-2/UCS-4
	(deprecated in C++17) (class template)
	(removed in C++26)

http://cppreference.com 	   2024.06.10	      std::codecvt_utf8_utf16(3)
home | help