◆ ucpstou8s_s()

errno_t Chusov::String::ucpstou8s_s	(	std::size_t *restrict	pcbUtf,
		char *restrict	pUtf,
		rsize_t	cbUtfMax,
		const ucp_t *restrict	pUcp,
		rsize_t	cbMaxConvert
	)

noexcept

Converts the specified sequence of Unicode 11.0 code points into a sequence of corresponding UTF-8 multibyte characters, and, if the specified output buffer is given by a non-NULL pointer, stores the specified number of bytes, constituting the converted UTF-8 multibyte string, to the output buffer terminating it with a null character.

Parameters

[out]	pcbUtf	is a mandatory pointer to an output buffer, that receives a number corresponding to a result of the conversion operation. If the pointer is `NULL`, there is a runtime-constraint violation. If the pointer is not `NULL`, and either any other runtime-constraint is violated, or an encoding error occurs, the value of `pcbUtf` is set to (size_t) -1. Otherwise, the function writes there a number of bytes of the UTF-8 multibyte string successfully retrieved from the conversion, not counting the terminating null character (if any).
[out]	pUtf	is an optional pointer to an output buffer receiving at most `cbUtfMax` bytes (see remarks) of the converted UTF-8 string. If a runtime-constraint violation occurs, and the `pUtf` pointer is not `NULL`, and `cbUtfMax` is greater than 0 and less or equal to `RSIZE_MAX`, pUtf[0] is set to the null character.
[in]	cbUtfMax	is a maximum number of bytes to be written to the `pUtf` buffer. If the `pUtf` pointer is `NULL`, the value of `cbUtfMax` must be zero. If `pUtf` is not `NULL`, `cbUtfMax` must not be greater than `RSIZE_MAX` or equal zero. If a number of code points, which corresponds to the cbMaxConvert bytes of the UTF-8 string, does not specify a null-terminated string of Unicode code points pointed to by `pUcp`, `cbUtfMax` must be greater than cbMaxConvert. If any of these conditions are not met, there is a runtime-constraint violation (see below).
[in]	pUcp	is a mandatory pointer to a zero-terminated string of Unicode 11.0 code points to be converted to its UTF-8 multibyte equivalent. No code points that follow the first found null code point (which is converted into a null multibyte character) will be examined or converted. If the `pUtf` pointer to the output buffer is `NULL`, the `pUcp` string must be zero-terminated, because all of its nonzero code points are converted, while the value of `cbMaxConvert` is ignored. If `pUtf` is not `NULL`, a maximal number of code points to convert is determined such that the converted result is not larger than the value specified by `cbMaxConvert` in bytes. If the `pUcp` string is zero-terminated within the bound, that corresponds to `cbMaxConvert` bytes of the multibyte string, the null code point is converted and written to the output buffer and the rest part of the input is ignored. If `cbMaxConvert` is greater than the maximal number of bytes to write to the output buffer, the input `pUcp` string must be zero-terminated within the bound, given by the number of characters that corresponds to `cbUtfMax` bytes of the UTF-8 string. Otherwise, there is a runtime-constraint violation.
[in]	cbMaxConvert	is a maximal number of bytes to write to the output buffer. No more than that number of bytes of the buffer will be modified. If the `pUtf` pointer is `NULL` the parameter is ignored by the function.

Returns: The function returns zero if no runtime-constraint violation and no encoding error occurred. Otherwise, a nonzero error code is returned.

The function implements the conversion of the specified string of Unicode 11.0 code points to a corresponding UTF-8 multibyte string. The function is built in a portable way to perform the conversion from of universally defined Unicode code points to UTF-8 codes independently of the current C locale.

It is a secure variant of the ucpstou8s function. The relation of ucpstou8s_s to ucpstou8s is similar to one of the analogous wcstombs_s function to its non-secure wcstombs 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 adherence to the following runtime-constraints.

Neither pcbUtf nor pUcp shall be a null pointer.
If pUtf is not a null pointer, then neither cbMaxConvert nor cbUtfMax shall be greater than RSIZE_MAX.
If pUtf is a null pointer, then cbUtfMax shall equal zero.
If pUtf is not a null pointer, then cbUtfMax shall not equal zero.
If pUtf is not a null pointer and cbMaxConvert is not less than cbUtfMax, then the conversion shall have been stopped because a terminating null code point was reached or because an encoding error occurred.
If there is a runtime-constraint violation, then the function does the following. If pcbUtf is not a NULL pointer, then *pcbUtf is set to (size_t)(-1). If pUtf is not a NULL pointer, and cbUtfMax is greater than zero and less than RSIZE_MAX, then pUtf[0] is set to the null character.

From these runtime-constraints it follows that if pUtf is not NULL, the pcbUtf receives an actual number of bytes written to the pUtf, not counting the terminating null character.

Also, unlike the non-secure ucpstou8s counterpart, the function verifies that all of the converted code points are valid as specified by the Unicode 11.0 standard.

Warning: The implementation adheres the requirements defined by the C11 standard and the ISO/IEC TR 24731-1 extension of C99 for the analogous wcstombs_s function, but differs from Microsoft wcstombs_s which does not conform the standard interface definition.

The differences are the following:

In the case of successful conversion the standard demands that the output value of pcbUtf, i.e. the number of successfully converted bytes, should not include the null terminator, whereas Microsoft definition includes it.
In case of an error the standard function does not necessarily set the errno code, while the Microsoft definition always does.
The standard requires that neither cbUtfMax nor cbMaxConvert must be greater than RSIZE_MAX whereas Microsoft does not define this requirement.
The standard considers equality of pcbUtf to NULL a runtime-constraint violation whereas Microsoft does not assert it.

See also: ucpstou8s;
u8stoucps_s;
ucptou8_s.