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

FreeBSD Manual Pages

  
 
  

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

NAME
       std::mbrtowc - std::mbrtowc

Synopsis
	  Defined in header <cwchar>
	  std::size_t mbrtowc( wchar_t*	pwc,

	  const	char* s,
	  std::size_t n,

	  std::mbstate_t* ps );

	  Converts a narrow multibyte character	to a wide character.

	  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 wide character and stores it
       in *pwc (if pwc
	  is not null).

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

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

Parameters
	  pwc -	pointer	to the location	where  the  resulting  wide  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 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 pwc  if  non-
       null) was
	      the null character
	    *  the number of bytes [1...n] of the multibyte character success-
       fully converted
	      from s
	    * static_cast<std::size_t>(-2) if the next n bytes	constitute  an
       incomplete, but
	      so far valid, multibyte character. Nothing is written to *pwc.
	    *  static_cast<std::size_t>(-1)  if	encoding error occurs. Nothing
       is written to
	      *pwc, the	value EILSEQ is	stored in errno	and the	value  of  *ps
       is left
	      unspecified.

Example
       // Run this code

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

	void print_mb(const char* ptr)
	{
	    std::mbstate_t state = std::mbstate_t(); //	initial	state
	    const char*	end = ptr + std::strlen(ptr);
	    int	len;
	    wchar_t wc;
	    while((len = std::mbrtowc(&wc, ptr,	end-ptr, &state)) > 0) {
		std::wcout << "Next " << len <<	" bytes	are the	character " <<
       wc << '\n';
		ptr += len;
	    }
	}

	int main()
	{
	    std::setlocale(LC_ALL, "en_US.utf8");
	    // UTF-8 narrow multibyte encoding
	    const char*	str = "z\u00df\u6c34\U0001d10b"; // or u8"z"
			      //					    or
       "\x7a\xc3\x9f\xe6\xb0\xb4\xf0\x9d\x84\x8b";
	    print_mb(str);
	}

Output:
	Next 1 bytes are the character z
	Next 2 bytes are the character
	Next 3 bytes are the character
	Next 4 bytes are the character

See also
	  mbtowc    converts the next multibyte	character to wide character
		    (function)
	  wcrtomb   converts a wide character to its multibyte representation,
       given state
		    (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::mbrtowc(3)

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

home | help