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

NAME
     std::codecvt_utf8 - std::codecvt_utf8

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

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

	std::codecvt_utf8  is a std::codecvt facet which encapsulates conversion
     between a
	UTF-8 encoded byte string and UCS-2 or UTF-32 character string	(depend-
     ing on the
	type  of  Elem).  This	std::codecvt facet can be used to read and write
     UTF-8 files,
	both text and binary.

	UCS-2 is the same encoding as UTF-16,  except  that  it  encodes  scalar
     (since C++23)
	values in the range U+0000-U+FFFF (Basic Multilingual Plane) only.

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 facet
		      (public member function)
	destructor    destroys a codecvt_utf8 facet
		      (public member function)

     std::codecvt_utf8::codecvt_utf8

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

	Constructs a new std::codecvt_utf8 facet, passes the  initial  reference
     counter refs
	to the base class.

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

     std::codecvt_utf8::~codecvt_utf8

	~codecvt_utf8();

	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

Notes
	Although the standard requires that this facet works with UCS-2 when the
     size of
	Elem is 16 bits, some  implementations	use  UTF-16  instead.  The  term
     "UCS-2" was
	deprecated and removed from ISO 10646.

	Since C++23, UCS-2 does not refer to its original definition anymore. It
     becomes a
	synonym of UTF-16, but with a smaller encoding range.

Example
	The  following	example  demonstrates the difference between UCS-2/UTF-8
     and
	UTF-16/UTF-8 conversions: the third character in the  string  is  not  a
     valid UCS-2
	character.

     // Run this code

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

      int main()
      {
	  // UTF-8 data. The character U+1d10b, musical sign segno, does not fit
     in UCS-2
	  std::string utf8 = "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 << "UTF-16 conversion produced " << utf16.size() <<  "  code
     units:\n"
		    << std::showbase << std::hex;
	  for (char16_t c : utf16)
	      std::cout << static_cast<std::uint16_t>(c) << ' ';

	  // the UTF-8 / UCS-2 standard conversion facet
	  std::wstring_convert<std::codecvt_utf8<char16_t>, char16_t> ucs2conv;
	  try
	  {
	      std::u16string ucs2 = ucs2conv.from_bytes(utf8);
	  }
	  catch(const std::range_error& e)
	  {
	      std::u16string	 ucs2	 =    ucs2conv.from_bytes(utf8.substr(0,
     ucs2conv.converted()));
	      std::cout << "\nUCS-2 failed after  producing  "	<<  std::dec  <<
     ucs2.size()
			<< " characters:\n" << std::showbase << std::hex;
	      for (char16_t c : ucs2)
		  std::cout << static_cast<std::uint16_t>(c) << ' ';
	      std::cout << '\n';
	  }
      }

Output:
      UTF-16 conversion produced 4 code units:
      0x7a 0x6c34 0xd834 0xdd0b
      UCS-2 failed after producing 2 characters:
      0x7a 0x6c34

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_utf16
	(C++11) 	      converts between UTF-16 and UCS-2/UCS-4
	(deprecated in C++17) (class template)
	(removed in C++26)
	codecvt_utf8_utf16
	(C++11) 	      converts between UTF-8 and UTF-16
	(deprecated in C++17) (class template)
	(removed in C++26)

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