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

NAME
     std::c32rtomb - std::c32rtomb

Synopsis
	Defined in header <cuchar>
	std::size_t  c32rtomb(	char*  s,  char32_t  c32,  std::mbstate_t* ps );
     (since C++11)

	Converts a UTF-32 character to its narrow multibyte representation.

	If s is not a null pointer, the function determines the number of  bytes
     necessary to
	store the multibyte character representation of c32 (including any shift
     sequences,
	and taking into account the current multibyte conversion state *ps), and
     stores the
	multibyte  character  representation  in the character array whose first
     element is
	pointed to by s, updating *ps as necessary. At most MB_CUR_MAX bytes can
     be written
	by this function.

	If s is a null pointer, the call  is  equivalent  to  std::c32rtomb(buf,
     U'\0', ps) for
	some internal buffer buf.

	If c32 is the null wide character U'\0', a null byte is stored, preceded
     by any
	shift sequence necessary to restore the initial shift state and the con-
     version state
	parameter *ps is updated to represent the initial shift state.

	The  multibyte	encoding  used by this function is specified by the cur-
     rently active C
	locale.

Parameters
	s   - pointer to narrow character array where  the  multibyte  character
     will be stored
	c32 - the 32-bit character to convert
	ps   - pointer to the conversion state object used when interpreting the
     multibyte
	      string

Return value
	On success, returns the number of bytes (including any shift  sequences)
     written to
	the  character	array whose first element is pointed to by s. This value
     may be 0,
	e.g. when processing the first char32_t in multi-char32_t-character  se-
     quence (does
	not occur in UTF-32).

	On  failure (if c32 is not a valid 32-bit character), returns -1, stores
     EILSEQ in
	errno, and leaves *ps in unspecified state.

Example
     // Run this code

      #include <climits>
      #include <clocale>
      #include <cuchar>
      #include <iomanip>
      #include <iostream>
      #include <string_view>

      int main()
      {
	  std::setlocale(LC_ALL, "en_US.utf8");
	  std::u32string_view	 strv	 =     U"zAae<degree>'dh";     //     or
     z\u00df\u6c34\U0001F34C
	  std::cout << "Processing " << strv.size() << " UTF-32 code units: [ ";
	  for (char32_t c : strv)
	      std::cout << std::showbase << std::hex << static_cast<int>(c) << '
     ';
	  std::cout << "]\n";

	  std::mbstate_t state{};
	  char out[MB_LEN_MAX]{};
	  for (char32_t c : strv)
	  {
	      std::size_t rc = std::c32rtomb(out, c, &state);
	      std::cout << static_cast<int>(c) << " converted to [ ";
	      if (rc != (std::size_t) - 1)
		  for (unsigned char c8 : std::string_view{out, rc})
		      std::cout << +c8 << ' ';
	      std::cout << "]\n";
	  }
      }

Output:
      Processing 4 UTF-32 code units: [ 0x7a 0xdf 0x6c34 0x1f34c ]
      0x7a converted to [ 0x7a ]
      0xdf converted to [ 0xc3 0x9f ]
      0x6c34 converted to [ 0xe6 0xb0 0xb4 ]
      0x1f34c converted to [ 0xf0 0x9f 0x8d 0x8c ]

See also
	mbrtoc32  converts a narrow multibyte character to UTF-32 encoding
	(C++11)   (function)
	do_out	   converts a string from InternT to ExternT, such as when writ-
     ing to file
	[virtual] (virtual protected member function of
		  std::codecvt<InternT,ExternT,StateT>)
	C documentation for
	c32rtomb

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