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

FreeBSD Manual Pages

  
 
  

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 el-
       ement 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 en-
       countered.
	    * The next wide character to be stored would exceed	len.

Notes
	  In most implementations, this	function updates a global  static  ob-
       ject 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
       function	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
       terminating L'\0',
	  written to the destination array.

	  On  conversion  error	 (if  invalid  multibyte character was encoun-
       tered), 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"z"
				//					    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: z

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
       reading 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)

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

home | help