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

FreeBSD Manual Pages

  
 
  

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 be-
       gins in the
	  conversion state described by	*ps, from the array whose  first  ele-
       ment is pointed to
	  by  *src  to	its wide character representation. If dst is not null,
       converted
	  characters are stored	in the successive elements of the wchar_t  ar-
       ray pointed to by
	  dst. No more than len	wide characters	are written to the destination
       array.

	  Each	multibyte  character is	converted as if	by a call to std::mbr-
       towc. 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 lo-
       cale) was
	      encountered. src is set to point at the beginning	of  the	 first
       unconverted
	      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
       terminating 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  encoun-
       tered), 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
       multibyte string.
	  This doesn't happen if dst is	a null pointer.

Example
       // Run this code

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

	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"z"
	    print_as_wide(mbstr);
	}

Output:
	Wide string: z
	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
       reading from file
	  [virtual] (virtual protected	member	function  of  std::codecvt<In-
       ternT,ExternT,State>)

http://cppreference.com		  2022.07.31		     std::mbsrtowcs(3)

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

home | help