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

NAME
     std::mbstowcs - std::mbstowcs

Synopsis
	Defined in header <cstdlib>
	std::size_t mbstowcs( wchar_t* dst, const char* src, std::size_t len );

	Converts a multibyte character string from the array whose first element
     is pointed
	to by src to its wide character representation. Converted characters are
     stored in
	the successive elements of the array pointed to by dst. No more than len
     wide
	characters are written to the destination array.

	Each  character is converted as if by a call to std::mbtowc, except that
     the mbtowc
	conversion state is unaffected. The conversion stops if:

	  * The multibyte null character was converted and stored.
	  * An invalid (in the current C locale) multibyte character was encoun-
     tered.
	  * The next wide character to be stored would exceed len.

Notes
	In most implementations, this function updates a global static object of
     type
	std::mbstate_t as it processes through the string, and cannot be called
	simultaneously by two threads, std::mbsrtowcs should  be  used	in  such
     cases.

	POSIX specifies a common extension: if dst is a null pointer, this func-
     tion returns
	the  number  of  wide  characters  that would be written to dst, if con-
     verted. Similar
	behavior is standard for std::mbsrtowcs.

Parameters
	dst - pointer to wide character array where  the  wide	string	will  be
     stored
	src - pointer to the first element of a null-terminated multibyte string
     to convert
	len - number of wide characters available in the array pointed to by dst

Return value
	On  success, returns the number of wide characters, excluding the termi-
     nating L'\0',
	written to the destination array.

	On conversion error (if invalid multibyte  character  was  encountered),
     returns
	static_cast<std::size_t> (-1).

Example
     // Run this code

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

      int main()
      {
	  std::setlocale(LC_ALL, "en_US.utf8");
	  std::wcout.imbue(std::locale("en_US.utf8"));
	  const    char*    mbstr    =	  "z\u00df\u6c34\U0001f34c";	//    or
     u8"zAae<degree>'dh"
			      // or "\x7a\xc3\x9f\xe6\xb0\xb4\xf0\x9f\x8d\x8c";
	  wchar_t wstr[5];
	  std::mbstowcs(wstr, mbstr, 5);
	  std::wcout << "wide string: " << wstr << '\n';
      }

Output:
      wide string: zAae<degree>'dh

See also
	mbsrtowcs converts a narrow multibyte character string to  wide  string,
     given state
		  (function)
	wcstombs  converts a wide string to narrow multibyte character string
		  (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
	mbstowcs

http://cppreference.com 	   2024.06.10			std::mbstowcs(3)
home | help