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

FreeBSD Manual Pages

  
 
  

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

NAME
       std::wcsrtombs -	std::wcsrtombs

Synopsis
	  Defined in header <cwchar>
	  std::size_t wcsrtombs( char* dst,

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

	  std::mbstate_t* ps );

	  Converts  a  sequence	 of wide characters from the array whose first
       element is pointed
	  to by	*src to	its narrow multibyte representation that begins	in the
       conversion
	  state	described by *ps. If dst is not	null, converted	characters are
       stored in the
	  successive elements of the char array	pointed	to  by	dst.  No  more
       than len	bytes are
	  written to the destination array.

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

	    * The null character was converted and stored. src	is  set	 to  a
       null pointer and
	      *ps represents the initial shift state.
	    *  A wchar_t was found that	does not correspond to a valid charac-
       ter in the current
	      C	locale.	src is set to point  at	 the  first  unconverted  wide
       character.
	    *  the next	multibyte character to be stored would exceed len. src
       is set to point
	      at the first unconverted wide character. This condition  is  not
       checked if dst is
	      a	null pointer.

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

Return value
	  On  success,	returns	 the  number of	bytes (including any shift se-
       quences,	but
	  excluding the	terminating '\0') written to the character array whose
       first element
	  is pointed to	by dst.	If dst is a null pointer, returns  the	number
       of bytes	that
	  would	have been written (again, excluding the	terminating null char-
       acter '\0').

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

Example
       // Run this code

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

	void print_wide(const wchar_t* wstr)
	{
	    std::mbstate_t state = std::mbstate_t();
	    std::size_t	len = 1	+ std::wcsrtombs(nullptr, &wstr, 0, &state);
	    std::vector<char> mbstr(len);
	    std::wcsrtombs(&mbstr[0], &wstr, mbstr.size(), &state);
	    std::cout << "multibyte string: " << &mbstr[0] << '\n'
		      << "Length, including '\\0': " <<	mbstr.size() <<	'\n';
	}

	int main()
	{
	    std::setlocale(LC_ALL, "en_US.utf8");
	    // UTF-8 narrow multibyte encoding
	    const wchar_t* wstr	= L"z\u00df\u6c34\U0001d10b"; // or L"z"
	    print_wide(wstr);
	}

Output:
	multibyte string: z
	Length,	including '\0':	11

See also
	  wcrtomb   converts a wide character to its multibyte representation,
       given state
		    (function)
	  mbsrtowcs  converts  a  narrow  multibyte  character	string to wide
       string, given state
		    (function)
	  do_out    converts a string from internT to externT,	such  as  when
       writing to file
	  [virtual]  (virtual  protected  member  function of std::codecvt<In-
       ternT,ExternT,State>)

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

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

home | help