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

NAME
     std::mbsrtowcs - std::mbsrtowcs

Synopsis
	Defined in header <cwchar>
	std::size_t mbsrtowcs( wchar_t* dst,

			       const char** src,
			       std::size_t len,

			       std::mbstate_t* ps );

	Converts a null-terminated multibyte character sequence, which begins in
     the
	conversion state described by *ps, from the array whose first element is
     pointed to
	by  *src  to its wide character representation. If dst is not null, con-
     verted
	characters are stored in the successive elements of  the  wchar_t  array
     pointed to by
	dst. No more than len wide characters are written to the destination ar-
     ray.

	Each  multibyte  character is converted as if by a call to std::mbrtowc.
     The
	conversion stops if:

	  * The multibyte null character was converted and stored. src is set to
     a null
	    pointer and *ps represents the initial shift state.
	  * An invalid multibyte character (according to the current  C  locale)
     was
	    encountered.  src  is set to point at the beginning of the first un-
     converted
	    multibyte character.
	  * The next wide character to be stored would exceed len. src is set to
     point at
	    the beginning of the first	unconverted  multibyte	character.  This
     condition is
	    not checked if dst is a null pointer.

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

Return value
	On success, returns the number of wide characters, excluding the  termi-
     nating L'\0',
	written  to  the  character array. If dst is a null pointer, returns the
     number of wide
	characters that would have been written given unlimited length.

	On conversion error (if invalid multibyte  character  was  encountered),
     returns
	static_cast<std::size_t>(-1),  stores EILSEQ in errno, and leaves *ps in
     unspecified
	state.

Notes
	This function moves the src pointer to the end of the  converted  multi-
     byte string.
	This doesn't happen if dst is a null pointer.

Example
     // Run this code

      #include <clocale>
      #include <cwchar>
      #include <iostream>
      #include <vector>

      void print_as_wide(const char* mbstr)
      {
	  std::mbstate_t state = std::mbstate_t();
	  std::size_t len = 1 + std::mbsrtowcs(nullptr, &mbstr, 0, &state);
	  std::vector<wchar_t> wstr(len);
	  std::mbsrtowcs(&wstr[0], &mbstr, wstr.size(), &state);
	  std::wcout << "Wide string: " << &wstr[0] << '\n'
		     << "The length, including '\\0': " << wstr.size() << '\n';
      }

      int main()
      {
	  std::setlocale(LC_ALL, "en_US.utf8");
	  const    char*    mbstr    =	  "z\u00df\u6c34\U0001f34c";	//    or
     u8"zAae<degree>'dh"
	  print_as_wide(mbstr);
      }

Output:
      Wide string: zAae<degree>'dh
      The length, including '\0': 5

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

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