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

NAME
     std::codecvt_utf16 - std::codecvt_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_utf16

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

	std::codecvt_utf16 is a std::codecvt facet which encapsulates conversion
     between a
	UTF-16 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-16 files in
	binary mode.

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

     std::codecvt_utf16::codecvt_utf16

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

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

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

     std::codecvt_utf16::~codecvt_utf16

	~codecvt_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

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, making this a
	non-converting locale. 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 decoding of UTF-16le file on a system
     with 32-bit
	wchar_t.  On a system with 16-bit wchar_t, decoding of the third charac-
     ter will fail
	because std::codecvt_utf16<char16_t> produces UCS-2, not UTF-16.

     // Run this code

      #include <codecvt>
      #include <cwchar>
      #include <fstream>
      #include <iostream>
      #include <locale>
      #include <string>

      void prepare_file()
      {
	  // UTF-16le data (if host system is little-endian)
	  char16_t utf16le[4] = {0x007a,	   //  latin  small  letter  'z'
     U+007a
				 0x6c34,	    //	 CJK  ideograph  "water"
     U+6c34
				 0xd834, 0xdd0b}; // musical sign segno U+1d10b

	  // store in a file
	  std::ofstream fout("text.txt");
	  fout.write(reinterpret_cast<char*>(utf16le), sizeof utf16le);
      }

      int main()
      {
	  prepare_file();
	  // open as a byte stream
	  std::wifstream fin("text.txt", std::ios::binary);
	  // apply facet
	  fin.imbue(std::locale(fin.getloc(),
	      new std::codecvt_utf16<wchar_t, 0x10ffff, std::little_endian>));

	  wchar_t c = 0;
	  for (std::cout << std::showbase << std::hex; fin.get(c);
	       std::cout << static_cast<std::wint_t>(c) << '\n');
      }

Output:
      0x7a
      0x6c34
      0x1d10b

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_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_utf16(3)
home | help