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

NAME
     std::c8rtomb - std::c8rtomb

Synopsis
	Defined in header <cuchar>
	std::size_t  c8rtomb( char* s, char8_t c8, std::mbstate_t* ps );  (since
     C++20)

	Converts a single code point from UTF-8 to a narrow multibyte character
	representation.

	If s is not a null pointer and c8 is the last code unit in a valid UTF-8
     encoding of
	a code point, the function determines the number of bytes  necessary  to
     store the
	multibyte  character  representation  of  that code point (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  c8	is  not  the final UTF-8 code unit in a representation of a code
     point, the
	function does not write to the array pointed to by s, only  *ps  is  up-
     dated.

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

	If c8 is the null character u8'\0', a null byte is stored,  preceded  by
     any shift
	sequence necessary to restore the initial shift state and the conversion
     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
	c8 - the UTF-8 code unit to convert
	ps  -  pointer to the conversion state object used when interpreting the
     multibyte
	     string

Return value
	The number of bytes stored in the array object (including any shift  se-
     quences). This
	may  be zero when c8 is not the final code unit in the UTF-8 representa-
     tion of a code
	point.

	If c8 is invalid (does not contribute to a sequence  of  char8_t  corre-
     sponding to a
	valid  multibyte  character), the value of the macro EILSEQ is stored in
     errno,
	static_cast<std::size_t>(-1) is returned, and the  conversion  state  is
     unspecified.

Notes
	Calls to c8rtomb with a null pointer argument for s may introduce a data
     race with
	other calls to c8rtomb with a null pointer argument for s.

Example
	 This section is incomplete
	 Reason: no example

See also
	mbrtoc8 converts a narrow multibyte character to UTF-8 encoding
	(C++20) (function)
	C documentation for
	c8rtomb

Category:
	  * Todo no example

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