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

FreeBSD Manual Pages

  
 
  

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

NAME
       std::mbtowc - std::mbtowc

Synopsis
	  Defined in header <cstdlib>
	  int mbtowc( wchar_t* pwc, const char*	s, std::size_t n );

	  Converts  a  multibyte character whose first byte is pointed to by s
       to a wide
	  character, written to	*pwc if	pwc is not null.

	  If s is a null pointer, resets the global conversion state  and  de-
       termines	whether
	  shift	sequences are used.

Parameters
	  s   -	pointer	to the multibyte character
	  n   -	limit on the number of bytes in	s that can be examined
	  pwc -	pointer	to the wide character for output

Return value
	  If  s	 is  not  a null pointer, returns the number of	bytes that are
       contained in the
	  multibyte character or -1 if the first bytes pointed to by s do  not
       form a valid
	  multibyte  character	or  0  if  s is	pointing at the	null character
       '\0'.

	  If s is a null pointer, resets its internal conversion state to rep-
       resent the
	  initial shift	state and returns 0 if the current multibyte  encoding
       is not
	  state-dependent  (does  not use shift	sequences) or a	non-zero value
       if the current
	  multibyte encoding is	state-dependent	(uses shift sequences).

Notes
	  Each call to mbtowc updates the internal global conversion state  (a
       static object of
	  type	std::mbstate_t,	only known to this function). If the multibyte
       encoding	uses
	  shift	states,	care must be taken to avoid backtracking  or  multiple
       scans. In any
	  case,	 multiple  threads should not call mbtowc without synchroniza-
       tion: std::mbrtowc
	  may be used instead.

Example
       // Run this code

	#include <clocale>
	#include <cstdlib>
	#include <cstring>
	#include <iostream>

	int print_mb(const char* ptr)
	{
	    std::mbtowc(nullptr, 0, 0);	// reset the conversion	state
	    const char*	end = ptr + std::strlen(ptr);
	    int	ret{};
	    for	(wchar_t wc; (ret = std::mbtowc(&wc, ptr, end -	ptr)) >	0; ptr
       += ret)
		std::wcout << wc;
	    std::wcout << '\n';
	    return ret;
	}

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

Output:
	z

See also
	  mbrtowc    converts  the next	multibyte character to wide character,
       given state
		    (function)
	  mblen	    returns the	number of bytes	in the next multibyte  charac-
       ter
		    (function)
	  do_in	     converts  a  string from ExternT to InternT, such as when
       reading from file
	  [virtual] (virtual protected member function of
		    std::codecvt<InternT,ExternT,StateT>)
	  C documentation for
	  mbtowc

http://cppreference.com		  2024.06.10			std::mbtowc(3)

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

home | help