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  deter-
     mines 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 con-
     tained 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  repre-
     sent 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 sta-
     tic object of
	type  std::mbstate_t, only known to this function). If the multibyte en-
     coding uses
	shift states, care must be  taken  to  avoid  backtracking  or	multiple
     scans. In any
	case,  multiple  threads should not call mbtowc without synchronization:
     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 "zAae<degree>'dh"
			    // or "\x7a\xc3\x9f\xe6\xb0\xb4\xf0\x9d\x84\x8b";
	  print_mb(str);
      }

Output:
      zAae<degree>'dh

See also
	mbrtowc   converts the next multibyte character to wide character, given
     state
		  (function)
	mblen	  returns the number of bytes in the next multibyte character
		  (function)
	do_in	   converts a string from ExternT to InternT, such as when read-
     ing 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)
home | help