chsvlib
chsv helper source code

◆ u8stoucps()

std:: size_t Chusov::String::u8stoucps ( ucp_t *restrict  pUcp,
const char *restrict  pUtf,
std::size_t  cchChars 
)
noexcept

Converts a sequence of UTF-8 characters into a sequence of corresponding Unicode 11.0 code points and writes at most the specified number of codes of the resulting sequence to a buffer.

Parameters
[out]pUcpis a pointer to an output buffer receiving at most cchChars code points, the UTF-8 string is converted to.
[in]pUtfis a pointer to a UTF-8 string to be converted to the sequence of code points. No UTF-8 characters that follow a null character (which is converted into a null wide character) will be examined or converted.
[in]cchCharsis a maximum number of code points that can be written to the output buffer.
Returns
If an invalid UTF-8 character is encountered so that its conversion cannot be performed, the function returns (size_t) (-1) and sets errno to EILSEQ. Otherwise, the function returns the number of code points written to the pUcp array, not including a terminating null code point, if any. The array will not be null-terminated if the value returned equals cchChars. Note that a successful return value by itself does not guarantee the validity of all UTF-8 codes nor the validity of the resulting code points.

The function is built in a portable way to perform the conversion of a UTF-8 code string to a string of scalar Unicode 11.0 code points independently of the current locale.

A successful execution of the function does not guarantee that all UTF-8 codes of the input string or the scalars of the output string are in a valid state as defined by the Unicode 11.0 standard. However, this verification is performed by the bound-checking alternative u8stoucps_s.

See also
u8stoucps_s;
ucpstou8s;
u8toucp.