◆ wctou8_s()

errno_t Chusov::String::wctou8_s	(	int *restrict	pStatus,
		char *restrict	pUtf,
		rsize_t	cbUtf,
		wchar_t	chUcs
	)

noexcept

Securely converts a given wide character, assumed to be encoded in the UCS format, to its UTF-8 representation.

Parameters

[out]	pStatus	is a mandatory pointer to an output buffer, that receives a number corresponding to a result of the conversion operation. The buffer is not modified if any of the runtime-constraints given below are violated. Otherwise, if the `pUtf` pointer is `NULL` the function writes 0 to the buffer, pointed to by `pStatus`, to indicate a state-independence of the UTF-8 encoding. Otherwise, the function writes either -1 or a number of bytes, written to the `pUtf` buffer, if the UCS-2 (or UCS-4 if a `wchar_t` object can hold UCS-4 values) wide character, given by `chUcs`, respectively does or does not correspond to a valid UTF-8 code. In no case will the signed integer pointed to by `pStatus` be set to a value greater than the `UTF8_LEN_MAX` macro.
[out]	pUtf	is a buffer where the multibyte UTF-8 equivalent of `chUcs` can be written. No more than `UTF8_LEN_MAX` and `cbUtf` bytes are stored into the buffer. If `pUtf` is `NULL`, the function only returns 0 (to indicate that the UTF-8 conversion is stateless) and ignores other parameters except for `pStatus`.
[in]	cbUtf	is a maximum number of bytes to be written to the buffer pointed to by the `pUtf` parameter. If the `pUtf` pointer is `NULL`, the value of `cbUtf` must be zero. If `pUtf` is not `NULL`, `cbUtf` must not be greater than `RSIZE_MAX` or less than a number of bytes needed to represent the specified wide character. If any of these conditions are not met, the function signals a runtime-constraint violation and interrupts the normal execution of code (see below). A value of `UTF8_LEN_MAX` is enough to represent any UTF-8 character.
[in]	chUcs	is a wide character given in UCS-2 (or UCS-4 if it is allowed by the wchar_t type) format. If `pUtf` is not `NULL`, the wide character is converted to its multibyte UTF-8 equivalent which is stored to the buffer pointed to by the `pUtf` parameter.

Returns: The function returns zero if successful, or an appropriate non-zero errno code if there is a runtime-constraint violation, or chUcs does not correspond to a valid multibyte character.

The function implements the conversion of a UCS-encoded wide character to the corresponding UTF-8 multibyte character. The function is built in a portable way to perform the conversion from the UCS to the UTF-8 format independently of the current locale.

It is a secure variant of the wctou8 function. The relation of wctou8_s to wctou8 is similar to one of the analogous wctomb_s function to its non-secure wctomb counterpart. The secure function is defined by the C11 standard (Annex K) as well as the extension ISO/IEC TR 24731-1 to the C99 standard.

The function verifies that the following runtime-constraints are not violated by a call:

Let n denote the number of bytes needed for UTF-8 representation of chUcs.
If pUtf is not NULL, then cbUtf must not be less than n, and cbUtf must not be greater than RSIZE_MAX. If pUtf is NULL, then cbUtf shall equal zero.
If there is a runtime-constraint violation, the function does not modify the number pointed to by pStatus, and, if pUtf is not NULL, no more than cbUtf bytes of pUtf will be accessed.

See also: wctou8;
wcstou8s_s;
u8towc.