Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

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

NAME
       std::mbrtoc16 - std::mbrtoc16

Synopsis
	  Defined in header <cuchar>
	  std::size_t mbrtoc16(	char16_t* pc16,

	  const	char* s,			 (since	C++11)
	  std::size_t n,

	  std::mbstate_t* ps );

	  Converts  a narrow multibyte character to UTF-16 character represen-
       tation.

	  If s is not a	null pointer, inspects at most n bytes of  the	multi-
       byte character
	  string,  beginning  with  the	 byte pointed to by s to determine the
       number of bytes
	  necessary to complete	the next multibyte  character  (including  any
       shift sequences).
	  If the function determines that the next multibyte character in s is
       complete	and
	  valid,  converts it to the corresponding 16-bit character and	stores
       it in *pc16 (if
	  pc16 is not null).

	  If the multibyte character in	*s corresponds to a multi-char16_t se-
       quence (e.g. a
	  surrogate pair in UTF-16), then after	the first call to  this	 func-
       tion, *ps is
	  updated  in such a way that the next call to mbrtoc16	will write out
       the additional
	  char16_t, without considering	*s.

	  If s is a null pointer, the values of	n and pc16 are ignored and the
       call is
	  equivalent to	std::mbrtoc16(nullptr, "", 1, ps).

	  If the wide character	produced is the	null character,	the conversion
       state *ps
	  represents the initial shift state.

	  The multibyte	encoding used by this function	is  specified  by  the
       currently active	C
	  locale.

Parameters
	  pc16	- pointer to the location where	the resulting 16-bit character
       will be written
	  s    - pointer to the	multibyte character string used	as input
	  n    - limit on the number of	bytes in s that	can be examined
	  ps   - pointer to the	conversion state object	used when interpreting
       the multibyte
		 string

Return value
	  The first of the following that applies:

	    * 0	if the character converted from	s (and stored in *pc16 if non-
       null) was
	      the null character
	    * the number of bytes [1...n] of the multibyte character  success-
       fully converted
	      from s
	    *  -3 if the next char16_t from a multi-char16_t character (e.g. a
       surrogate pair)
	      has now been written to *pc16. No	bytes are processed  from  the
       input in	this
	      case.
	    *  -2  if  the  next  n bytes constitute an	incomplete, but	so far
       valid, multibyte
	      character. Nothing is written to *pc16.
	    * -1 if encoding error occurs. Nothing is written  to  *pc16,  the
       value EILSEQ is
	      stored in	errno and the value of *ps is unspecified.

Example
       // Run this code

	#include <iostream>
	#include <iomanip>
	#include <clocale>
	#include <cstring>
	#include <cwchar>
	#include <cuchar>

	int main()
	{
	    std::setlocale(LC_ALL, "en_US.utf8");

	    std::string	str = "z\u00df\u6c34\U0001F34C"; // or u8"z"

	    std::cout  <<  "Processing	"  <<  str.size()  <<  " bytes:	[ " <<
       std::showbase;
	    for(unsigned char c: str) std::cout	<< std::hex << +c << ' ';
	    std::cout << "]\n";

	    std::mbstate_t state{}; // zero-initialized	to initial state
	    char16_t c16;
	    const char *ptr = &str[0], *end = &str[0] +	str.size();

	    while(std::size_t rc = std::mbrtoc16(&c16, ptr, end	 -  ptr	 +  1,
       &state))
	    {
		std::cout << "Next UTF-16 char:	" << std::hex
			  << static_cast<int>(c16) << "	obtained from ";
		if(rc == (std::size_t)-3)
		    std::cout << "earlier surrogate pair\n";
		else if(rc == (std::size_t)-2)
		    break;
		else if(rc == (std::size_t)-1)
		    break;
		else {
		    std::cout << std::dec << rc	<< " bytes [ ";
		    for(std::size_t n =	0; n < rc; ++n)
			std::cout   <<	 std::hex   <<	 +static_cast<unsigned
       char>(ptr[n]) <<	' ';
		    std::cout << "]\n";
		    ptr	+= rc;
		}
	    }
	}

Output:
	Processing 10 bytes: [ 0x7a 0xc3 0x9f 0xe6 0xb0	0xb4  0xf0  0x9f  0x8d
       0x8c ]
	Next UTF-16 char: 0x7a obtained	from 1 bytes [ 0x7a ]
	Next UTF-16 char: 0xdf obtained	from 2 bytes [ 0xc3 0x9f ]
	Next UTF-16 char: 0x6c34 obtained from 3 bytes [ 0xe6 0xb0 0xb4	]
	Next UTF-16 char: 0xd83c obtained from 4 bytes [ 0xf0 0x9f 0x8d	0x8c ]
	Next UTF-16 char: 0xdf4c obtained from earlier surrogate pair

See also
	  c16rtomb  convert a 16-bit wide character to narrow multibyte	string
	  (C++11)   (function)
	  do_in	     converts  a  string from externT to internT, such as when
       reading from file
	  [virtual] (virtual protected	member	function  of  std::codecvt<In-
       ternT,ExternT,State>)

http://cppreference.com		  2022.07.31		      std::mbrtoc16(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=std::mbrtoc16&sektion=3&manpath=FreeBSD+Ports+15.0>

home | help